[wp-hackers] Codex function page proposal
brian at nerdlife.net
Sun Dec 28 07:36:52 GMT 2008
I agree that something beyond PHPdoc is necessary, and that Wiki-style is
definitely the way to go, but I think more automation is needed.
Ideally, I'd love to see a bot that goes through and creates wiki pages for
all (or a subset of) functions with at the very least a link to the PHPdoc,
and then monitors the PHPdoc and, if it changes, sticks a "potentially out
of date" notice on the page, along with a category to the same effect. The
perks of this are twofold:
1) A place for examples and quirks for each function that at least tells you
when it's out of date
2) Every release, all someone has to do is look at the "potentially out of
date" category and see what's changed.
For those who think that we don't need a function doc beyond PHPdoc, I'll
give you my use case. I have a plugin that encourages adding a slice of
code into one's theme. I provide copy-and-paste style code samples, but I'd
also like to provide links to documentation on more advanced functionality.
I don't want to link to PHPdoc because I find it's intimidating for all but
experienced coders. I'd like to have something at least a little more
When I first started hacking on PHP, inviting documentation was key to me
learning the language. Without as easy and intuitive a documentation as
that found on php.net, I would have been a lot more lost.
On Sun, Dec 28, 2008 at 2:21 AM, dave jaggy <jayarjo at gmail.com> wrote:
> Very interesting discussion here. Personally I had a very hard time
> starting with WordPress API and I can't say that Codex helped in that,
> sometimes it took me to wrong places, sometimes it still does. I never
> knew about the http://phpdoc.wordpress.org/trunk/. That's great thank
> you. It's much more easier then browse an API in search of comments.
> But I still think that the whole thing is little misleading. One can
> become experienced PHP coder without entering the API directly. I
> don't think that everyone has enough motivation and courage to do so
> anyway. But in WordPress world it's kinda - 'you just have to do it'.
> There seems no other way to really understand what exactly is
> happening and why.
> I think, that documentation must be one and it has to be automated, at
> least at code comments level. Why not move to PHP-like documentation
> style, but - leave a space for user contiributed descriptions and
> examples. We can do it on the same page. For example, there will be
> only phpdoc version of function description, until someone decides to
> contribute additional information. And let it be added underneath the
> phpdoc piece and let it be denoted that is is USER CONTRIBUTED and
> that you guys at WordPress core are not responsible for what is
> written down there ('cause it's really is not self-explanatory).
> So there can be two parts on every page - phpdoc one which will be
> updated automatically when patch will be done, and user contributed
> wiki. And there can be a third one - comments (raw ideas - people post
> comments easily, I mean working on wiki needs some kind of
> preparation, and posting a comment does not). Someone more skilled in
> writing may take those comments later and comile good wiki part out of
> I think that's the best structure. I would use it with great relieve I
> should say.
> On Sun, Dec 28, 2008 at 9:06 AM, Gaarai <gaarai at gaarai.com> wrote:
> > I don't like working without a plan, but if that's the best I can hope
> > I guess that will have to suffice.
> > I've removed the parameter, return, and error sections from my example
> > When I link directly to the function in the PHPdoc, it of course only
> > to the inner-most frame. Is there/could there be a way to link to the
> > PHPdoc site while having that internal frame show the desired function?
> > Please give me a tap on the shoulder when you've got ideas.
> > Chris Jean
> > http://gaarai.com/
> > http://wp-roadmap.com/
> > Jacob Santos wrote:
> >> Changes are not made by coders with commit access for PHPdoc. Anyone can
> >> create a patch on trac.wordpress.org to update, add, or replace the
> >> documentation. The design of the phpdoc site can be changed to that of
> >> PHP site.
> >> I don't want to prevent work being done on the Codex to move this
> >> my contention is just the parameter and return type. If you remove those
> >> then it should be fine with a link to the trunk phpdoc, since it will be
> >> up-to-date version.
> >> I would put more effort into the Codex, but like I said, it is extremely
> >> boring and time consuming. Most pages take at least four hours and I
> >> don't have the time for that. Well, I do, but I'll rather spend it doing
> >> something else.
> >> The plan most likely will be from whoever puts for the effort and time
> >> accomplish the task. Hashing out details is too time consuming and
> >> completely depressing. Trust me, with documentation, planning amounts to
> >> doing and not doing equals to it never getting done. Only with putting
> >> step forward will this be accomplished.
> >> I'll be walking beside you as will others, I believe, but I'm not going
> >> be there at the beginning or even the middle. I don't expect others will
> >> there with you either. However, setting a standard for which others can
> >> at and parrot will do the Codex community a lot of good.
> >> Just keep the parameter and return types out of it.
> >> Jacob Santos
> >> Gaarai wrote:
> >>> Good stuff Jacob. This is the kind of information I need.
> >>> Since I had no idea of the scope of what you are doing with the inline
> >>> documentation until I read this, I'm sure that many other people share
> >>> same lack understanding on what is going on with that. Quite frankly, I
> >>> could count on my fingers the number of days that I even knew of the
> >>> existence of phpdoc.wordpress.org.
> >>> So, we have a huge problem, and I think that the problem is even bigger
> >>> than I previously thought.
> >>> Here is what we have currently:
> >>> * The Codex
> >>> o Observations
> >>> + Changes can be made by anyone
> >>> + Creates a wealth of information
> >>> o Strengths
> >>> + Can find just references to just about anything a
> >>> developer would like to work with
> >>> + Includes function references, API references, and
> >>> general help documents
> >>> + Is often cited and thought of as the location to get
> >>> WordPress documentation
> >>> + Can be modified at any time
> >>> o Weaknesses
> >>> + The organization is poor at best. Everything is in a
> >>> mesh that is poorly linked. It's not difficult to find
> >>> more than one page with similar content that are
> >>> linked in completely different ways
> >>> + Search is next to worthless
> >>> + Much of the information is either severely out of
> >>> date, incorrect, or lacks quality examples of use
> >>> + Impossible to track staleness of content
> >>> * The PHPdoc Site
> >>> o Observations
> >>> + Changes can only be made by coders with commit access
> >>> to core
> >>> o Strengths
> >>> + Comprehensive list of every documented function and
> >>> class in WP Core
> >>> + Provides details that are helpful to coders
> >>> + More consistent and accurate information by comparison
> >>> to the Codex
> >>> o Weaknesses
> >>> + Not nearly as well known as the Codex
> >>> + The changes only occur when committed (this creates an
> >>> inability to update documentation on tagged versions)
> >>> + Has formatting issues (such as the presentation of
> >>> query-style parameter options)
> >>> + More limited scope when compared to Codex due to
> >>> smaller number of editors
> >>> It's clear to see that we have two systems that each have their merits.
> >>> My concept was limited in that it attempted to address the shortcomings
> >>> the Codex without regards to the existence of the PHPdoc.
> >>> I'm going to shelve my Codex ideas and plans for now. What we need to
> >>> is discuss what the ideal solution for documentation is and then begin
> >>> implementing that. In other words, I now see that the problem isn't
> just the
> >>> Codex, it's the fact that there isn't a plan.
> >>> So, I don't know what needs to happen to create this plan and begin
> >>> executing it, but I would definitely like to be a part of it. What most
> >>> likely needs to occur is a number of us that are interested in fixing
> >>> current state of WP documentation discuss ideas back and forth until we
> >>> up with a vision of what WP documentation should be and then create a
> >>> to make that a reality.
> >>> Most likely, this will have to be taken over to the wp-docs site. I'm
> >>> sending this to the wp-hackers group since it started here, and I want
> >>> get as many developers/designers in on this as possible.
> >>> Thoughts?
> >>> Chris Jean
> >>> http://gaarai.com/
> >>> http://wp-roadmap.com/
> >> _______________________________________________
> >> 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
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
More information about the wp-hackers