[wp-hackers] Codex function page proposal
Charles E. Frees-Melvin
charles at cefm.ca
Sun Dec 28 15:04:13 GMT 2008
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
> * What can we do to help you get the PHPdoc to an ideal state?
> Chris Jean
> 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
>> 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
>> 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
>> 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>
>>> Very interesting discussion here. Personally I had a very hard time
>>> starting with WordPress API and I can't say that Codex helped in
>>> sometimes it took me to wrong places, sometimes it still does. I
>>> knew about the http://phpdoc.wordpress.org/trunk/. That's great
>>> 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
>>> 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
>>> contribute additional information. And let it be added underneath
>>> 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
>>> comments easily, I mean working on wiki needs some kind of
>>> preparation, and posting a comment does not). Someone more skilled
>>> 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.
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
More information about the wp-hackers