[crossfire] Documentation revamp, was spoiler generation

[Mark Wedel]

Nicolas Weeger wrote:
> Well, my opinion is that server / code / developer documentation should be in 
> doxygen format, part of the sources and integrated in the doxygen-generated 
> docs.
> 
> It would be much easier to bundle everything together this way.

  Can you give some better examples of that?

  I will admit that the current layout of documentation (or maybe more 
specifically, the doc dir) isn't great.  To find out if something is documented, 
one basically has to resort to grep, as what file something is documented in 
isn't really the most consistent.

  Documentation right now is basically ad hoc - as something new is added, often 
a new file is added.

  I'm not sure what the doc structure should look like, but it definitely needs 
to get cleaned up.  One complication is that there are potentially 3 different 
audiences for any documentation: players, mapmakers, and coders (one could 
perhaps even add a fourth - script writers).

  Why I think this gets complicated is there is a question on how to organize 
it.  For example, lets take some object that does something interesting but non 
trivial, so that you need directions for it use.

  For players, you'd describe how to use that item
  For map makers, you'd have to describe the different fields the item uses, and 
how it affects the object
  For coders, you may want to describe the internals of how the object operates, 
so that some other coder needs to modify the code, they have some better idea of 
how some tricky code may work.

  Now one method is to basically split that information into 3 different places 
- the player information may be in the help files or the client.  The map maker 
information may be in the editor, and the developer information may be in the 
code itself.  The problem is that makes it pretty hard to find the relevant 
documentation.

  The other way is that all of this is in one file/place.  In that way, if the 
coder extends the code, he knows all the places he needs to update the 
documentation.  It is also useful, as the map maker sees a description of how an 
item is used, and the coder sees what the fields do and how it is supposed to work.

  Now if doxygen can be used to somehow separate these pieces out, that would 
make me more willing to look at it.  For example, something like

**start_help_...
help documentation
**end_help
**start_editor_...
information for the editor
**end_editor
(rest of this is just coder information, so doesn't really need to be pulled out)

  And also if doxygen can pull out the ** stuff and leave the documentation, 
that might be nice.

  I'd still say that even in that case, doxygen should be used more as a 
documentation building tool and not a formatting tool.  In fact, for the vast 
majority of documentation, I really like plain text - I can always view it 
easily, update it easily, etc.  I'd think that for most of the documentation, 
there is actually little need for formatting in most cases.