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.

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.

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.