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@xxxxxxxxxxxx
// 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@xxxxxxxxxxxx
// 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@xxxxxxxxxxxxxxxxxxxxxxxxxxx
--
PHP General Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
