[wp-hackers] Codex function page proposal

[Gaarai]

Thanks for adding your thoughts Brian and Dave. I've been pondering the 
same things, but I wanted to see if anyone else was thinking along these 
lines.

While a merging by links between PHPdoc and the Codex may be the best 
solution with everything being the way it is, I wonder why we shouldn't 
just go "back to the drawing board" and think about a way to do this 
better. I believe that we (Brian, Dave, and myself) all agree that 
having a single repository of information in a consistent format is of 
far greater value than two cross-linked systems with different formats, 
different content, and different target audiences.

That said, Jacob said that the PHPdoc output could be modified. I'd like 
to request more information about that from Jacob before I start 
dreaming up solutions for the Codex again.

    * Does the output use a template system allowing the output to look
      like anything?
    * Do you know of any consistency issues with the inline
      documentation as it is now? In other words, has there been a way
      to ensure that all changes to the inline documentation are in the
      same consistent format?
    * What is the current state of the inline documentation format? Is
      the current format of the inline documentation exactly what you
      intended, or is it a work in process which needs more work to
      fully implement what you desire for it to have? I'm not asking
      about depth of content, I'm only asking about the format of the
      content.
    * What can we do to help you get the PHPdoc to an ideal state?

Chris Jean
http://gaarai.com/
http://wp-roadmap.com/



Brian Krausz wrote:
> 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
> user-friendly.
>
> 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.
>
> --Brian
>
> 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
>> them.
>>
>> I think that's the best structure. I would use it with great relieve I
>> should say.