I'm having a bit of trouble forming an opinion on this. I believe you are correct that this needs to be addressed. I'm less certain that your proposal is the way to do it. I would like to see more comments in the code. I'm hesitant to suggest commenting to that extent though, as it can drown the code in comments, making it hard to check header files as a quick reference once you're already familiar with the functionality. But part of that is I've never used a system like Doxygen before. I have no sense of what using such a system is really like in practice. I've heard such systems work well with code folding, but I still use MSVC 6 for Outpost 2 code, which doesn't have code folding. That would make it harder to ignore the bulk of documentation.
I'm also not entirely sure this addresses the overview part that you've brought up. I understand how this addresses documenting individual functions. I'm not sure how these systems are used to document a group of similar functions, such as all trigger creation functions, which all share certain commonalities. Or similarly, how to document a group of related member functions for a class, separate from the entire class.
Lastly, I believe one of the strengths of these documentation systems is that putting the documentation in with the code makes it easier to keep both code and documentation in sync. But due to the no-source-code nature of Outpost 2, I don't see the code in the header files ever changing, so the problem of keeping things in sync doesn't seem to exist here.
I would like better documentation. Both of individual functions, and overview of how to use sets of functions, or general concerns for certain features. I would love to put documentation on the website somehow. I also wouldn't mind a small intro to C++ that's targeted at what you'll need to know for level programming. I'm not completely sold on using Doxygen to generate that documentation. I'm also not exactly against the idea either. I'm not sure I'll have a sense of whether or not it's a good idea until someone actually tries it. I guess I just have a strange sense that another method or another tool might be more appropriate. But then, I may be overlooking some of Doxygen's features.
I'd be curious to know what other people think about the documentation. In particular, would having lots of documentation in the header files themselves be good, or distracting. I think having more and better documentation is something most people will want. I'm not so sure if people want it all in the header files. It might be nice to document a small file from the API to compare what it looks like with and without the extra documentation. From what I've seen of other projects, the amount of comments for the documentation often dwarfs the actual code itself by an order of magnitude.
What should go in the documentation? Perhaps:
- function signature
- description of all inputs
- description of return value
- error conditions
- behavior or performance notes
- example usage
- multiple examples of usage?
- links to related functions or classes
Including it all could be useful, but would take up quite a bit of space.
