If you’re like me, when you’re coding things for a personal project, you won’t create any documentation. You’re the only one who will ever see or use this code, so why would you? Right? Let’s just add some comment here and there and it’ll be ok. Right? But sometime, somewhere along the road, you’ll wish you would have started documenting things.
Personnaly, I don’t like to write documentation. I prefer to write code and comments. However I know how important documentation is. That’s why I chose to start early with HexEngine and started to use Doxygen.
Doxygen extracts docomentation from the comments. Meaning that “all you have to do” to have some documentation for your projet is to adapt your comments style to doxygen comments style. Here’s an exemple of a function header.
/** * Some function description * * @param someParam Some description for this param * @param someOtherParam Some description for this other param * * @return Some explaination of what the function return ************************************************************/
To streamline my documentation process, here’s what I did:
- Downloaded and Installed Doxygen windows binary.
- Use the Doxygen GUI to create default.doxygen and save in $(SolutionDir)\docs\default.doxygen
- VC++ 2005 Express > Tools > External Tools > Add
Title: doxygen
Command: C:\Program Files\doxygen\bin\doxygen.exe
Arguments: $(SolutionDir)\docs\default.doxyfile
Initial Directory: $(SolutionDir)
Check Use output window - VC++ 2005 Express > Tools > Customize > Keyboard
Show Commands Containing: Tools.ExternalCommand3 (You’ll have to find the correct external tool to assign
Use new shortcut in: Global
Press shortcut keys: CTRL+D
Assign
And voila! Now when I press CTRL+D, doxygen runs according to the configuration in default.doxygen and generate my documentation.
Ah, yes, documenting your code! Something I always have to force myself to do. Whenever I start on something I tell myself I’m gonna document everything properly, even though nobody except me will see the code. When I start I usually add plenty of comments, but later on it always slows down considerably. The problem is that in the beginning, your code is easy readable and you know what each line does. Once the project becomes a bit larger, though, it becomes more and more difficult. I wish something like this existed for Torque Game Builder.
hehe yeah me too. I always find myself just trying to make something work, debug, fix, debug, etc.. and then 2-3 days later I’ll have to go back and add comments. It’s a bad habit I’m trying to break… At least Doxygen helps me not to forget about the function header. That’s a start :)
My guess would be that since Torque Script is not very far from the C/C syntax, doxygen might work.