[wp-hackers] Proposal for a function commenting convention

[Robin Adrianse]

I highly doubt it, but someone more knowledgeable about the PHP code would
know for sure.

On 10/13/07, Matt <speedboxer at gmail.com> wrote:
>
> 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/
> _______________________________________________
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-hackers
>