Hi all

Back in the day, last time I created a sizeable (100k lines) c++ project, I would use doxygen to generate a html documentation of the object model and the system in general. This worked very well and was automatically updated and copied to the Web as part of the build process.

This was six years or more ago, and of course times change and software evolves. Now I am again writing a large project where it is getting to the point where documentation will be key to it being bad or good code. I was thinking of doing the same again, and tying doxygen into the build process, but I thought it best to ask for others opinions on what they use for the same process. I could Google up several different programs to do what doxygen does but this won't provide a game developers opinion on it. that is what I am after, so if anyone has any wisdom to impart, I would appreciate it

Thanks!

I've usually used Doxygen in my own projects... but, on every professional game team that I've ever worked on, there's been usually no code documentation... and it's often not that bad!

Sometimes wikis are used, but they often become outdated, and wrong/outdated documentation is worse than none. Same goes for doxygen/etc comments...

So these days, while I still like doxygen somewhat, the most important thing is that the code itself is extremely readable, the interfaces are predictable, and there's short comments explaining the concepts involved -- "the code is the documentation" should be as common as other catch phrases such as "premature optimization is the root of all evil"

These days with doxygen, I prefer to use it mosly to write overviews, and other stuff that I could easily do with another markup language, rather than using it for the common purpose of automatically tagging every argument to every function. Such automatic documentation is often useless, simply creating tautologies such as "Count: contains the number of items"...

These days with doxygen, I prefer to use it mosly to write overviews, and other stuff that I could easily do with another markup language, rather than using it for the common purpose of automatically tagging every argument to every function.

Yeah, I remember originally setting out with that intention, and later on just documenting classes in general and the methods/constructors. The parameter names generally speak for themselves.

If you ask me it's more about discipline then selecting the right tool.
Here's what I do with my engine codebase:

- each member function has comments above it, always saying what the function's purpose is and what it does/ returns
- I have an xls sheet with one line per function of each class, so I can easily find back stuff
- class diagrams I make in word or excel, as a part of my game design document

If you like I can share the xls format, if you want to try it out.
Without discipline it will not be usable (when I add a class and finish the implementation, the xls is updated. When I change the interface of a function I add a comment // NEW, so one in a while I can update changed stuff). Which ofcourse would be the same with all tools :)

I use plain old comments. I don't make closed-source libraries, so I have no need to generate a second set of documentation from the code.

I use "the code is the documentation" methodology mentioned by Hodgman.

My function declarations have comments explaining what they do in the header files. The function names are usually pretty straight-forward also, and sometimes it's not even necessary to comment their purpose.

I occasionally add comments before class definitions also, but the majority of the time this isn't necessary.

I don't need external documentation - I can just Shift+Click on any func usage to jump to its definition, or I can Ctrl+Shift+F to locate a function in the source.

However, if I was releasing my code as a public library (that's more than just a single header), I'd run something to just pull the comment and function definitions out of the header, or else markup the existing comments with something like Doxygen, because I definitely like html documentation for code I didn't write myself.

At my work we use Visual Studio, so we add documentation comments to our functions in the style VS supports - triple slashes with XML tags. While the above coders are certainly right about code being readable to not need documentation, it's still nice to have the IDE fill in tooltips as you're typing in case you don't remember exactly what a certain parameter does.

Example:

///<summary>This function does stuff</summary>
///<param name="arg1">Something passed in</param>
///<returns>True on success</returns>
bool MyFunction(int arg1);

I've usually used Doxygen in my own projects... but, on every professional game team that I've ever worked on, there's been usually no code documentation... and it's often not that bad!
Sometimes wikis are used, but they often become outdated, and wrong/outdated documentation is worse than none. Same goes for doxygen/etc comments...

Yep, same here. There's usually a wiki that drifts, and really only exists for the new hires to get some clue of how things were set up originally. After that, it's all about learning your way around the system.

Different for actual engines in regular use across wide groups of people, though, or other middleware projects. You don't get to skimp on the documentation there... for SlimDX we used the built in VS doc system but through Sandcastle with a custom front end bolted on. For pure C++ I'd just use Doxygen, but I'd only bother for public APIs.

I try to write code that's self-documenting as much as possible. Most documentation I write is either in the form of brainstorming notes - which typically go in a Word doc or a paper notebook and aren't terribly organized - or in the form of comments explaining why I'm doing what I'm doing (as opposed to what I'm doing).

For C++, Doxygen is still king of the hill as far as reference documentation goes, and I believe the last time I looked into it they now support the Microsoft-style triple-slash XML comments in addition to their own annotations. If you're already familiar with those, stick with them.

I do wish there were a tool based on Clang's front-end though -- Doxygen maintains their own parser, AFAIK, and that seems redundant now, and I would assume that it also loses some deeper context that could be important for documentation. Clang would not.

Doxygen is also nice since it generates static pages. This means that you can distribute the docs in a .zip file, or serve them up from a very basic (and innexpensive) web server, or even serve them up right from a github repo (this feature is called Github Pages) if you're open source and on GitHub (EDIT: actually, I believe you can have a public GitHub Pages site attached to a private Repo, if you want to keep the source hidden, but distribute DLLS / Headers on a release package.

But since programmer documentation is what I do for a living, I can also say that reference is good, but its not enough. People want good reference, but they also assume its there and take it for granted. What they usually ask for is code samples, example projects, and help understanding the general patterns of using your API. They usually don't care about overview-type topics unless they're really high quality, an overview that's just average is usually seen as just getting in the way.