Blog

Doxygen Chosen for Clay's Documentation Generator

Posted by david on 12 August 2012 at 4:10 am

From Doxygen.org:

"Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D."

I've struggled to find time to write documentation, especially when I'd much prefer to write code instead. Lately I've been trying to get better at writing documentation inside the code. I decided if I used something that would generate documentation from the code, I could at least provide some type of documentation source. It's a start at least. 

Doxygen takes comments placed in source code and uses it to produce a formatted reference documentation. I've been testing it out on my development code and it works really well. I have found, of course, that some of the my comments aren't up to Doxygen's standards, so I will have to fix quite a bit of my in-code documentation. One of the plus sides to Doxygen (and I'm not saying other Doc generators don't do this) is it supports for Markdown documents as well. That is a huge plus, actually, because all of the docs I have written so far are in Markdown format. GitHub also uses Markdown, so it works out quite well.

I am currently in the process of performing a very large upgrade to some of the foundational structures within Clay. Many of the features I had planned to hold off for Clay Framework 2.0 are making their way into the current code base. During this process I've gone from chicken-scratch code, I once used, to better formatted code and standardization of a lot of the ways I write code. Nearly all of the source files have been getting formatting changes, so this is a good time to document as much as possible within the code.

I'm getting ready to fill the void of not having a web site dedicated to the Clay Project, as you may have guessed from my logo annoucement earlier. I'm going to start it out simple and grow it as I can. My main concern is content (is king), so I want to have as much documentation as possible. Doxygen will help me fill that void and save some time in the process.

Comments

Log in to comment

No comments yet!