How Do You Like To Do It? - Commenting Headers

[eluser]adamfairholm[/eluser]
Hey all,

We've all done it - you are building a helper or library or something and you want to give it a commenting header to explain some things. All the cool libraries and helpers and plugins do it.

The thing is, I've seen a lot of people do it in different ways. There doesn't seem to be an *official* way do it, but I was wondering what everyone's way of doing things is. I'll post my template.

Note: This discussion is utterly pointless, but why not.

I do it pretty simple - I guess you'd say I'm a minimalist. I keep it simple with just plain old * things, and then the pertinent info that would help someone looking for info.

Code:

/*
********  Name of Class ********
*
* A short little blurb about what this baby does.
*
* @author      My Name
* @link     Link of there is any online documentation
* @module      Maybe it goes with a module - if so, that goes there.
*
* Any instructions about the uses of the class go up here.
*/

I've seen some pretty crazy stuff going on with | symbols and all sorts of @ things. Maybe you have an ASCII "It's a Trap!" in there. Post your own, or not.

[eluser]Colin Williams[/eluser]
Here's a good resource to follow: http://manual.phpdoc.org/HTMLframesConve...s.pkg.html

[eluser]adamfairholm[/eluser]
Whoops, I thought module was one of those, I guess not. Thanks for that resource though, Colin - I guess @LinK should be @tutorial perhaps.

[eluser]Derek Allard[/eluser]
If you want to see the commenting style that we (EllisLab) use, we've documented it in the developer guidelines. There's some really good info in there. Here's the specific link to commenting. http://expressionengine.com/docs/develop...commenting