[wp-hackers] Proposal for a function commenting convention

[Matt]

Ya... but... would documenting all (or most) of the functions make a huge
impact on load times on the files since they'll be loaded with useless (in
the executing sense) comments?

On 10/13/07, Jacob <wordpress at santosj.name> wrote:
>
> Err, yeah. Have you any thoughts of how the version which functions were
> added are going to be found? I'm not even sure the devs would know about
> every function. You'll find that checking repository log is neat for
> files, but doesn't really tell you much about functions. Unless of
> course you check each repository commit.
>
> (After some contemplation, one could perhaps, download or find an old
> 1.5 version and just start from there. Use the 1.5 version and just say
> that any and all functions that existed in that version started with
> that version and ignore the previous versions.)
>
> Good luck with that. I would advise against trying it, because I can see
> into the future and I can tell you straight up and right now that you're
> not going to get very far before you give up. I know I would and you
> would have to be completely diehard and god-like to do so. Meaning that
> if you were to complete such a task, I would build a shine in your honor.
>
> I think that going forward, it would be a good idea. Going back and
> adding @since isn't going to do any good, since well, plugin authors
> already know that their plugins don't work.
>
> Besides that. I think that if you were (and by you, I mean we) going to
> add phpDoc comments, it should also include information about the
> function. What the function does and what it is used for and how in the
> code is more useful than @since (not that I'm saying @since is useless,
> because it isn't, it is more useful for future documentation than past).
>
> In which case, I agree that the convention should be
>
> /**
> * function_name() - Short description
> *
> * Long Description
> *
> * @param Stuff here
> * @return Stuff here
> * @since Version here (if known. Taxonomy should be updated to include
> @since 2.3)
> */
>
> The reason for this convention is that the first thing a person wants to
> know is what the function purpose is without the filler crap. The second
> thing a coder wants to know after they've decided upon that, is more
> about what it does and how to use it. If you are really hardcore, you'll
> add (@example Code) or (@tutorial Text ... Code).
>
> Meaning, while the "function_name()" portion is redundant in the
> phpDocumentor context, it is still useful for the reader browsing the
> code. You don't have to keep scrolling down to see what the function is,
> it is just right there at the top!
>
> I did some work on the Taxonomy documentation. I would like very much if
> someone else would work on that. In that case, would it be neat if we
> picked a file and assigned functions to whoever wants them to write
> documentation for it? I'll be more willing to take up the task, if I
> knew others were undergoing the same torture I was.
>
> Cheers,
>
> Jacob Santos
>
> Jared Bangs wrote:
> > On 10/13/07, Ozh <ozh at planetozh.com> wrote:
> >
> >> On 10/13/07, Robin Adrianse <robin.adr at gmail.com> wrote:
> >>
> >>> PHPDoc has a @since variable, which was made specifically for this
> >>>
> >> purpose.
> >>
> >> But I'd really like at least a simple "// added in WP 2.4" even for
> >> basic non phpdoc'ed stuff :)
> >>
> >
> >
> > +1 for using PHPDoc as a standard way of doing this. If we're going to
> go
> > back through and add comments to the existing code, it should definitely
> be
> > in a consistent format.
> > _______________________________________________
> > wp-hackers mailing list
> > wp-hackers at lists.automattic.com
> > http://lists.automattic.com/mailman/listinfo/wp-hackers
> >
>
> _______________________________________________
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-hackers
>



-- 
Matt (speedboxer at gmail.com)
http://mattsblog.ca/