Re: PHP documentation solutions? (PHPDoc, Doxygen, ???)

Jay Blanchard wrote:

[snip] In the spirit of re-inventing the wheel... I rolled my own JinnDoc. [/snip] My single largest arguement against these kinds of tools were the additional mark-up required. Code commentary, done properly, can yield the same results without additional mark-up. I'd rather be able to insert a code comment or html comment with a simple 'type' to tell me what the commentary is. It makes it much more universal where auto-doc harvesters are concerned and removes the requirement for page level elements to be stated first, etc. example(s) /* type=description * * describe whatever is being described here */ or <!-- type="description" whatever is being described --> or $myBigVar = 'large' //type=variable

Before each function I create, I have this: /* // Function : getCategoryEmail // Description : Retrieves a list of email addresses based on // past orders per category // Requires : $catids (Array) - Array of category ids // $id (Integer) - The DCHOB site id // Optional : None // Returns : Array with email addresses and stats; false on // failure // Author : John Nichel // Email : john@kegworks.com // Created : 20 Mar 05 // Modified : // Modified By : // Mod Email : // Mod Date : */ Major block of code... /* // Description : Checks if customer has come in thru BorderFree; // sets appropriate flags if true // Expected : If a BorderFree id is set either in the POST or // GET request, assign id to users session so it // so that it will be available should customer // attempt to purchase. If id does not match known // BF syntax, email admin with name/value pair; set // flag for normal checkout with logging // Author : John Nichel // Email : john@kegworks.com // Created : 20 Mar 05 // Modified : // Modified By : // Mod Email : // Mod Date : */ Variables... $foo = "bar" // This is what this variable is for So on, and so forth. I am the IT department here, so I'm not worried about documenting it yet. ;) -- John C. Nichel IV Programmer/System Admin (ÜberGeek) Dot Com Holdings of Buffalo 716.856.9675 jnichel@dotcomholdingsofbuffalo.com