[wp-hackers] Hook (Filter, Action) Documentation Idea

[Jacob Santos]

On Thu, Sep 9, 2010 at 5:08 AM, hakre <hanskrentel at yahoo.de> wrote:

> ----- Ursprüngliche Mail ----
>
> > Von: Jacob Santos <wordpress at santosj.name>
> > An: wp-hackers at lists.automattic.com
> > Gesendet: Mittwoch, den 8. September 2010, 22:29:33 Uhr
> > Betreff: Re: [wp-hackers] Hook (Filter, Action) Documentation Idea
> >
> > Well, my point was that given the large number of hooks, that it is
>  almost
> > impractical to create a separate method or function describing each
>  hook.
>
> Yeah documentation sucks. Really. It's only work, is it impractical?
> Probably.
>

Reasons it might be impractical:

1. It has to be at least 80% to 90% complete. The people in the API group
might be willing to help and I might also be willing. It would be better if
it gets upwards to 100% complete.
2. Motivation. You gots to have a lots of it.
3. If more people are not adding inline documentation than those who do,
then yes, it will be impractical.
4. Developers naturally gear more towards the lazy and unless the culture of
the project or at least the individual programmer is for inline
documentation and documentation in general, then it is fighting a losing
battle.

Inline documentation from 2.5 to 2.8 was an experiment to see if people
would actually maintain it after it was "complete." So far, meh, if the API
documentation group doesn't actually do something about it, then I think in
a few years or so, it would have been a failure.

Previous experience has proven to me that many people are willing to do a
few spots here and there, but unless someone throws down and attempts it
towards completion, then it never will. It was subtle, but I was giving you
props. If you are thinking about documenting a majority of the hooks through
your system, then it is going to be hard or at least it was in my
experience.


> My Hook Tracer so far successfully extracts the name of the hook and
> locates the
> calling location and type (filter, action, direct or ref_array method). I'm
> currently fiddling with parameters and I might be able to even substract
> the
> VARY part directly from code because of variable usage.
>

Ah, that is much better. For some reason I was thinking you were going to be
doing it all manually. Yeah, I would probably with with the automated
process as well. While you are at it, you could also add the skeleton phpdoc
stuff as well or was that what you were referring to below?

> Also, given  the
> > already intermittent nature of inline documentation corrections, updates
>  and
> > additions; it seems somewhat problematic to force people into adding a
>  new
> > method when they add a new filter or action.
>
> Forcing? This is not why I suggested it. I was looking for feedback. I can
> understand that some think that this looks like just as much work. And
> therefore
> crazy.
>

No, it is what I suggest and suggested. If the culture is not geared towards
providing and maintain inline documentation, then there is no point in
having it. It does no good to have 5% of contributors adding and maintaining
inline documentation and another 95% not caring, knowing, or maintaining it
themselves. As the battle is lost, the documentation becomes incomplete or
worse, incorrect.


>
> > Given that those  writing
> > patches might not even know about the method Hakre  describes
>
> Yeah. But on the opposite most developers know about PHP and Comments, and
> the
> Docblock conventions. So it's mainly build on exisiting things which makes
> it
> easy to adopt.


I was thinking after I commented and your idea, I believe, is the best one
since it fully takes into account existing conventions to the best possible
solution. There just needs to be a note saying, "Hey, when adding a filter
or action, go here." And note the location. Majority of people aren't going
to do it, but those that do will limit the work that is required in the
future.

P.S. rereading this, it appears as if I'm attempting to persuade you not to
continue. That is not the case, and I'll be willing to help once you have a
complete file or files.

Jacob Santos