XML comment style suggestions?

Ye' old general discussion board. Basically, for everything that isn't covered elsewhere. Come here to shoot the breeze, shoot your mouth off, or whatever suits your fancy.
This forum is not for asking programming related questions.

Moderator: General Moderators

Post Reply
alex.barylski
DevNet Evangelist
Posts: 6267
Joined: Tue Dec 21, 2004 5:00 pm
Location: Winnipeg

XML comment style suggestions?

Post 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 :)
josh
DevNet Master
Posts: 4872
Joined: Wed Feb 11, 2004 3:23 pm
Location: Palm beach, Florida

Re: XML comment style suggestions?

Post 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.
Charles256
DevNet Resident
Posts: 1375
Joined: Fri Sep 16, 2005 9:06 pm

Post by Charles256 »

guess i gotta break down and learn XML...
josh
DevNet Master
Posts: 4872
Joined: Wed Feb 11, 2004 3:23 pm
Location: Palm beach, Florida

Post 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)
alex.barylski
DevNet Evangelist
Posts: 6267
Joined: Tue Dec 21, 2004 5:00 pm
Location: Winnipeg

Re: XML comment style suggestions?

Post 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 :)
josh
DevNet Master
Posts: 4872
Joined: Wed Feb 11, 2004 3:23 pm
Location: Palm beach, Florida

Post 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?
alex.barylski
DevNet Evangelist
Posts: 6267
Joined: Tue Dec 21, 2004 5:00 pm
Location: Winnipeg

Post 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 :oops:

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...
Post Reply