Page 1 of 1
XML comment style suggestions?
Posted: Fri Nov 25, 2005 10:05 pm
by alex.barylski
I have countless times changed the way I comment modules, classes and functions...
So I figured I would standardize the way I do this by defining a set of XML tags to describe each section of a comment stub...
But I need suggestions, seeing how I'm not an XML expert or anything...
example:
Code: Select all
<history>
<revision>
<date value="Nov.15.05" />
<author name="Joe Sox" email="test@hotmail.com" />
<remark>
Some changes were added...
</remark>
</revision>
</history>
I usually include a copyright notice in module stubs, but not for class or functions...
A list of authors for each function is usually added...
Am I missing any fields...??? Any ideas, suggestions, etc???
I've considered how ugly XML is going to be inside comments, but it's for the best I think

Re: XML comment style suggestions?
Posted: Fri Nov 25, 2005 10:22 pm
by josh
Hockey wrote:I do this by defining a set of XML tags to describe each section of a comment stub...
Inegenious
Hockey wrote:
But I need suggestions, seeing how I'm not an XML expert or anything...
How about a way to embed information about the class itself, about its public methods (It's API), I see several advantages
Write your XML first and unit test from it.
Generate 'help files' about your objects dynamically
etc.
Posted: Fri Nov 25, 2005 10:30 pm
by Charles256
guess i gotta break down and learn XML...
Posted: Fri Nov 25, 2005 10:33 pm
by josh
Charles256 wrote:guess i gotta break down and learn XML...
XML = not much to learn (for basic documents at least), you make your own doctypes, if you know HTML you already know enough to write a simple xml document.
XML tags are not predefined. You must "invent" your own tags.
(you could say you make it up as you go)
Re: XML comment style suggestions?
Posted: Fri Nov 25, 2005 10:57 pm
by alex.barylski
jshpro2 wrote:Hockey wrote:I do this by defining a set of XML tags to describe each section of a comment stub...
Inegenious
Hockey wrote:
But I need suggestions, seeing how I'm not an XML expert or anything...
How about a way to embed information about the class itself, about its public methods (It's API), I see several advantages
Write your XML first and unit test from it.
Generate 'help files' about your objects dynamically
etc.
I thought of that, but thats overkill IMHO...unless you plan on generating docs from it...but I have been working on a script which works on PHP tokens and (when finished) generate API docs from source code, not XML comments...
XML comments were more for a standard way of defining comment stubs...and possibly easily editing comments via a a custom XML editor
Basically just sugar coded candy on top of API generated docs

Posted: Sat Nov 26, 2005 11:19 am
by josh
Well the advantage I saw to the auto doc generation, is unless you name your functions in a seemingly abnoxious way your documentation is blatantly confusing:
Code: Select all
function Add_Number_to_variable($x) {
return($x+1);
}
With xml data about the function you are freed to:
1) Name your functions whatever you want
2) Produce in the documentation an explanation of exactly what each function does
All that aside, I can't really think of much else.. PHP version #? OS it was written for? Short description of what the class does?
Posted: Sat Nov 26, 2005 12:26 pm
by alex.barylski
jshpro2 wrote:Well the advantage I saw to the auto doc generation, is unless you name your functions in a seemingly abnoxious way your documentation is blatantly confusing:
Code: Select all
function Add_Number_to_variable($x) {
return($x+1);
}
With xml data about the function you are freed to:
1) Name your functions whatever you want
2) Produce in the documentation an explanation of exactly what each function does
All that aside, I can't really think of much else.. PHP version #? OS it was written for? Short description of what the class does?
OS and PHP version...didn't even think of those
I've now been looking at XML in my comments for about 6 hours...
I can't yet decide whether they have clout or just add clutter...
It's certainly slightly more work to keep on top of...