[wp-hackers] Codex function page proposal

[Charles E. Frees-Melvin]

I also wanted to throw into the conversation the following http://codex.wordpress.org/User:CharlesClarkson#Individual_Function_Reference_Pages

On 28-Dec-08, at 8:51 AM, Gaarai wrote:

> 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.
> _______________________________________________
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-hackers