Document Fog of War API

[Luashine]

There're a couple things I dont like about it, most importantly the terminology. I want to discuss this again and seriously.

This is called the Fog of War API. The FOW itself has 3 states (quoting my first draft here):

---

• FOG_OF_WAR_MASKED (1): Black mask, an unexplored map area.
  • If "Masked areas are partially visible" is enabled in Map Properties, unexplored areas are shown in dark grey. You can see the terrain, but no units.
  • If disabled, unexplored areas are black and not visible.
• FOG_OF_WAR_FOGGED (2): Haze, a previously explored map area that is currently not visible.
  • You can see the terrain, but no units.
• FOG_OF_WAR_VISIBLE (4): A fully visible map area.
• Other (non-existent) fog types do nothing.

---

This seems fine until you begin dealing with individual function descriptions like FogMaskEnable, FogEnable. What I don't like about this is the ambiguous use of terms. On one hand this entire thing (API and concept) is called Fog of War. On the other hand, WC3 has the "mask vs fog" differentiation. In particular reusing "fog" seems to be a bad idea for clarity. It's not ideal to copy-paste this explanation everywhere.

I've asked in Hive Discord: GrapesOfWath would stay with these terms. Water would (probably) stay too but said this about my (over)simplification attempts (fair):

not sure if the name should refer to the appearance you should call css classes after semantics, too

---

Options include:

1. (Current) Official: mask, fog ("explored"), visible. Good: no extra layers of terminology; Downside: full explanation must be read to be understood
2. Water's synonyms like: blurred, misty, veiled, faded, dimly, fuzzy, hazy, diffuse. Good: no clash on the word fog. Bad: uncommon words with little benefit.
3. Going by appearance: "black/blacked", "gray/greyed". Good: simple English, refers to in-game experience. Bad: gray remains ambiguous (masked is black/gray WE Option)
4. Middle ground: "hard fog" and "soft fog". Good: sort of understandable (yet masked black/gray still somewhat ambiguous). Bad: extra terminology, does not instantly make a connection like the literal "black & gray" (imo)

[lep]

I think it's alright to have technical explanations. And the style is what we are currently doing anyways: attach the documentation to one specific native or type and explicitly link to it. I prefer that over duplicating documentation.

[Luashine]

Stayed with official terminology, added links to fogstate where they're explained. Ready for review.