PDA

View Full Version : Writing Documentation




Eraserhead
Jul 27, 2007, 05:52 PM
I have realised that the source code for my application (http://www.erasersoft.com/) is well, very poor, so I've been trying to get my documentation up to scratch, I tried using HeaderDoc, but Apple seem to have abandoned it and it is very buggy (it adds a month to dates, so thinks today is the 27th August) and it is difficult to get to parse the code.

Anyhow what can I use? I am programming in Objective C so sadly (I guess) can't use Javadoc, which is excellent.

EDIT: Attached is the relevent header file, and the documentation folder in a zip, apart from the dates I may be being a little unfair about HeaderDoc so I'll take another look tomorrow, but good documentation comments are still welcome.



gnasher729
Jul 27, 2007, 06:24 PM
I have realised that the source code for my application (http://www.erasersoft.com/) is well, very poor, so I've been trying to get my documentation up to scratch, I tried using HeaderDoc, but Apple seem to have abandoned it and it is very buggy (it adds a month to dates, so thinks today is the 27th August) and it is difficult to get to parse the code.

Anyhow what can I use? I am programming in Objective C so sadly (I guess) can't use Javadoc, which is excellent.

Personally I think the most important thing is writing code that is readable, using identifiers that express clearly what they mean. Objective C has the additional advantage that parameter names are visible in each call. If I can look at the source code of a function and understand immediately what it does, then I don't need any documentation.

Beyond that, it is useful to have documentation that explains how a class is used. Automatic tools usually don't do that, because they just document individual functions. And as I said, with well-written code that kind of documentation doesn't add very much.