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. _______________________________________________ crossfire mailing list [email protected] http://mailman.metalforge.org/mailman/listinfo/crossfire
