Question

I am currently working on a project that I would like to create a help file for but I was hoping someone could suggest the best practices for this.

The help file would mainly be for me, and say anyone in the future that might take over my project etc, and would mostly identify objects or pieces of code that I have implemented and a description of what they are for etc.

This is something I have found in the apple developer library, here but im not sure what this is or how to use it..

Answer 1

I have decided to go with Apples HeaderDocs as it it already built in it generates very similar results to those that are created with the application listed above (re: html output)

Its simple as you just use structured comments inside your header tags along the lines of

/*!
 @class myclass
 @discussion enter any text here that can span multiple lines etc
*/

The great thing being you can comment methods, functions, classes, parameters etc.

then when you compile the headers inside cmd line using the gathered headers script it will combine all of your header comments into a MasterDoc.html inside a directory you specify like so

>headerdoc2html -o outputdir ExampleHeaders
>gatherheaderdoc outputdir

This style of documenting suites me personally because I like to comment my code alot however I lack the structure that this will now bring to my comments, so really its killing two birds with one stone.

The only let down I feel is that it might not be as flexible as those listed before this post… So yea I guess users prefrence… Now off to learn more