[wp-hackers] Codex function page proposal

[dave jaggy]

Just thought that we can try to bring this idea to life ourselves.
Personally I'd be glad to participate in a project like that.

We can even host it separately for some time, until it gets a place in
WordPress world. It is possible to find a way to parse a phpdoc part
of documentation, but Codex one will be a little more cumbersome,
unless someone will let us to fetch it in raw format through some
simple API. Maybe there is one already or maybe it is already
integrated into wiki and we just need someone to tell us about that?

Dave

On Sun, Dec 28, 2008 at 7:04 PM, Charles E. Frees-Melvin
<charles at cefm.ca> wrote:
> 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
>
> _______________________________________________
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-hackers
>