[PATCH] Documentation

classic Classic list List threaded Threaded
11 messages Options
Reply | Threaded
Open this post in threaded view
|

[PATCH] Documentation

Rich Bowen
Example documentation patch. Note, this is just one example, and not one
of the most useful ones - just one of the simplest ones. More complex
examples would also contain a simple explanation of the return value.


Index: functions.php
===================================================================
--- functions.php       (revision 3535)
+++ functions.php       (working copy)
@@ -47,6 +47,9 @@
        return $j;
 }

+/** current_time( $type = ('mysql'|'timestamp')
+*               [ , $gmt = (true|false) ] )
+*/
 function current_time($type, $gmt = 0) {
        switch ($type) {



--
Rich Bowen
[hidden email]
_______________________________________________
wp-hackers mailing list
[hidden email]
http://lists.automattic.com/mailman/listinfo/wp-hackers
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] Documentation

Andy Skelton
On 2/16/06, Rich Bowen <[hidden email]> wrote:
> +/** current_time( $type = ('mysql'|'timestamp')
> +*               [ , $gmt = (true|false) ] )
> +*/

If this is meant to help people read the code, I think it's too cryptic.

Receipt:
one opinion, two cents.
delivery, no charge.

Andy
_______________________________________________
wp-hackers mailing list
[hidden email]
http://lists.automattic.com/mailman/listinfo/wp-hackers
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] Documentation

Craig-16
>From someone trying to learn about the guts of WP, it means not a thing! :\
Craig.


On 2/16/06, Andy Skelton <[hidden email]> wrote:

>
> On 2/16/06, Rich Bowen <[hidden email]> wrote:
> > +/** current_time( $type = ('mysql'|'timestamp')
> > +*               [ , $gmt = (true|false) ] )
> > +*/
>
> If this is meant to help people read the code, I think it's too cryptic.
>
> Receipt:
> one opinion, two cents.
> delivery, no charge.
>
> Andy
> _______________________________________________
> wp-hackers mailing list
> [hidden email]
> http://lists.automattic.com/mailman/listinfo/wp-hackers
>
_______________________________________________
wp-hackers mailing list
[hidden email]
http://lists.automattic.com/mailman/listinfo/wp-hackers
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] Documentation

Rich Bowen
In reply to this post by Andy Skelton
Andy Skelton wrote:
> On 2/16/06, Rich Bowen <[hidden email]> wrote:
>> +/** current_time( $type = ('mysql'|'timestamp')
>> +*               [ , $gmt = (true|false) ] )
>> +*/
>
> If this is meant to help people read the code, I think it's too cryptic.

It lists the arguments (type and gmt) with, in this case, their possible
values (type can be either 'mysql' or 'timestamp', and gmt can be either
true or false). The [ ] indicates an optional argument. This syntax is
fairly common in man-page type documentation.

I'm going for API documentation, not "use this to learn how to write
PHP" documentation. It is assumed that folks will be willing to learn
what the notation means. And once you've learned it, the docs become clear.

Please note that this syntax came out of more than an hour of IRC
conversation as being just about the most verbose thing that would
possibly be accepted.

There is a (I think rather unwarranted) fear of making the code files
larger.

However, this isn't a patch that's been accepted. It's proposed. Don't
just say it's too cryptic. Say what you think it should be instead. If
you write a paragraph about what the function does, the patch will
almost certainly be rejected. I've been assured of that by the IRC
conversation. I'd rather not waste time submitting patches that I know
will be rejected.

--
Rich Bowen
[hidden email]
_______________________________________________
wp-hackers mailing list
[hidden email]
http://lists.automattic.com/mailman/listinfo/wp-hackers
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] Documentation

Craig-16
On 2/17/06, Rich Bowen <[hidden email]> wrote:
>
>
> I'm going for API documentation, not "use this to learn how to write
> PHP" documentation. It is assumed that folks will be willing to learn
> what the notation means. And once you've learned it, the docs become
> clear.


I'm totally willing to learn what the notation means, but my concept of the
inline documentation is a tool to help me figure out what a particular
function is about. I'm not looking for a tutorial at every variable and
array on where the data are coming from, how they are processed, and where
they are going after that bit of code is executed. If I only have a short
explanation, or indeed a label of some kind, then I know that I can search
Codex for more detailed information.

Understand that I don't have any issue with your suggestion as it stands,
however I guess we are both approaching this from two interpretations of
needs. As I said, I don't expect a "War and Peace" explanation, but I do
need something that I can use to at least know what to do research for.

This is why Carthik right asserted that we need to agree on some terms of
reference and such prior to embarking upon the actual work. If it is
determined that the inline docs are appropriately done as per your API
notation, then so be it, but at this point, I know that there are at least
two people with two different concepts of what the ID project is for and
should accomplish.

I totally appreciate and understand your concerns regarding
"over-documentation" as well as doing a whole crapload of work that may
actually be rejected by those in charge of commits, and I whole-heartedly
agree that we cannot have that situation.

Craig.
_______________________________________________
wp-hackers mailing list
[hidden email]
http://lists.automattic.com/mailman/listinfo/wp-hackers
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] Documentation

Carthik Sharma
On 2/17/06, Craig <[hidden email]> wrote:
> On 2/17/06, Rich Bowen <[hidden email]> wrote:
> >
> >
> > I'm going for API documentation, not "use this to learn how to write
> > PHP" documentation. It is assumed that folks will be willing to learn
> > what the notation means. And once you've learned it, the docs become
> > clear.

Rich, I suppose we both agree we are working towards something that is
immediately useful to programmers. The benefit of using a system, such
as phpdocumentor, for one, is that people can read the same comments,
and browse the source at an automatically generated webpage. So it
might be better to adapt to an existing system rather than create a
new lingo (like it is better to use WP that to hand code a blog :) )

> I'm totally willing to learn what the notation means, but my concept of the
> inline documentation is a tool to help me figure out what a particular
> function is about. I'm not looking for a tutorial at every variable and
> array on where the data are coming from, how they are processed, and where
> they are going after that bit of code is executed. If I only have a short
> explanation, or indeed a label of some kind, then I know that I can search
> Codex for more detailed information.

Craig,
You will get the parameters(Variables), their "type", what they do,
and what the whole function does, which should be good enough, I
guess. All this, with the phpdocumentor style of commenting.

Carthik.
--
Ph.D. Candidate
University of Central Florida
Homepage: http://carthik.net

_______________________________________________
wp-hackers mailing list
[hidden email]
http://lists.automattic.com/mailman/listinfo/wp-hackers
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] Documentation

Craig-16
On 2/17/06, Carthik Sharma <[hidden email]> wrote:
>
> <snip>
> Craig,
> You will get the parameters(Variables), their "type", what they do,
> and what the whole function does, which should be good enough, I
> guess. All this, with the phpdocumentor style of commenting.
>
> Carthik.


Works for me!
Craig.
_______________________________________________
wp-hackers mailing list
[hidden email]
http://lists.automattic.com/mailman/listinfo/wp-hackers
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] Documentation

Rich Bowen
In reply to this post by Carthik Sharma
Carthik Sharma wrote:

> On 2/17/06, Craig <[hidden email]> wrote:
>> On 2/17/06, Rich Bowen <[hidden email]> wrote:
>>>
>>> I'm going for API documentation, not "use this to learn how to write
>>> PHP" documentation. It is assumed that folks will be willing to learn
>>> what the notation means. And once you've learned it, the docs become
>>> clear.
>
> Rich, I suppose we both agree we are working towards something that is
> immediately useful to programmers. The benefit of using a system, such
> as phpdocumentor, for one, is that people can read the same comments,
> and browse the source at an automatically generated webpage. So it
> might be better to adapt to an existing system rather than create a
> new lingo (like it is better to use WP that to hand code a blog :) )

I think I've been won around to this syntax. I'm concerned, however,
with the notion that we'll only document long functions. This causes
them to be left out of the generated webpage entirely.

--
Rich Bowen
[hidden email]
_______________________________________________
wp-hackers mailing list
[hidden email]
http://lists.automattic.com/mailman/listinfo/wp-hackers
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] Documentation

Robert Deaton
On 2/17/06, Rich Bowen <[hidden email]> wrote:

> Carthik Sharma wrote:
> > On 2/17/06, Craig <[hidden email]> wrote:
> >> On 2/17/06, Rich Bowen <[hidden email]> wrote:
> >>>
> >>> I'm going for API documentation, not "use this to learn how to write
> >>> PHP" documentation. It is assumed that folks will be willing to learn
> >>> what the notation means. And once you've learned it, the docs become
> >>> clear.
> >
> > Rich, I suppose we both agree we are working towards something that is
> > immediately useful to programmers. The benefit of using a system, such
> > as phpdocumentor, for one, is that people can read the same comments,
> > and browse the source at an automatically generated webpage. So it
> > might be better to adapt to an existing system rather than create a
> > new lingo (like it is better to use WP that to hand code a blog :) )
>
> I think I've been won around to this syntax. I'm concerned, however,
> with the notion that we'll only document long functions. This causes
> them to be left out of the generated webpage entirely.
Like I said in the other thread, I will personally be documenting them
anyways and submitting the patches, no matter how trivial the
functions may be. Perhaps such will be a wakeup call in the sense that
this function pollution crap could use some fixing as well.

--
--Robert Deaton
http://somethingunpredictable.com

_______________________________________________
wp-hackers mailing list
[hidden email]
http://lists.automattic.com/mailman/listinfo/wp-hackers
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] Documentation

Rich Bowen
Robert Deaton wrote:

> On 2/17/06, Rich Bowen <[hidden email]> wrote:
>> Carthik Sharma wrote:
>>> On 2/17/06, Craig <[hidden email]> wrote:
>>>> On 2/17/06, Rich Bowen <[hidden email]> wrote:
>>>>> I'm going for API documentation, not "use this to learn how to write
>>>>> PHP" documentation. It is assumed that folks will be willing to learn
>>>>> what the notation means. And once you've learned it, the docs become
>>>>> clear.
>>> Rich, I suppose we both agree we are working towards something that is
>>> immediately useful to programmers. The benefit of using a system, such
>>> as phpdocumentor, for one, is that people can read the same comments,
>>> and browse the source at an automatically generated webpage. So it
>>> might be better to adapt to an existing system rather than create a
>>> new lingo (like it is better to use WP that to hand code a blog :) )
>> I think I've been won around to this syntax. I'm concerned, however,
>> with the notion that we'll only document long functions. This causes
>> them to be left out of the generated webpage entirely.
>
> Like I said in the other thread, I will personally be documenting them
> anyways and submitting the patches, no matter how trivial the
> functions may be. Perhaps such will be a wakeup call in the sense that
> this function pollution crap could use some fixing as well.

Speaking of function pollution ...

I've been experimenting with Zend Studio, and in addition to practically
writing all the phpdoc for you, it also does code analysis for stuff
like variables that are never used, and code that is never executed. I
think if we're concerned about "bloat" we could stand to drop the
function or two that never gets used.

--
Rich Bowen
[hidden email]
_______________________________________________
wp-hackers mailing list
[hidden email]
http://lists.automattic.com/mailman/listinfo/wp-hackers
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] Documentation

Rob Miller-4
Rich Bowen wrote:

> Robert Deaton wrote:
>  
>> On 2/17/06, Rich Bowen <[hidden email]> wrote:
>>    
>>> Carthik Sharma wrote:
>>>      
>>>> On 2/17/06, Craig <[hidden email]> wrote:
>>>>        
>>>>> On 2/17/06, Rich Bowen <[hidden email]> wrote:
>>>>>          
>>>>>> I'm going for API documentation, not "use this to learn how to write
>>>>>> PHP" documentation. It is assumed that folks will be willing to learn
>>>>>> what the notation means. And once you've learned it, the docs become
>>>>>> clear.
>>>>>>            
>>>> Rich, I suppose we both agree we are working towards something that is
>>>> immediately useful to programmers. The benefit of using a system, such
>>>> as phpdocumentor, for one, is that people can read the same comments,
>>>> and browse the source at an automatically generated webpage. So it
>>>> might be better to adapt to an existing system rather than create a
>>>> new lingo (like it is better to use WP that to hand code a blog :) )
>>>>        
>>> I think I've been won around to this syntax. I'm concerned, however,
>>> with the notion that we'll only document long functions. This causes
>>> them to be left out of the generated webpage entirely.
>>>      
>> Like I said in the other thread, I will personally be documenting them
>> anyways and submitting the patches, no matter how trivial the
>> functions may be. Perhaps such will be a wakeup call in the sense that
>> this function pollution crap could use some fixing as well.
>>    
>
> Speaking of function pollution ...
>
> I've been experimenting with Zend Studio, and in addition to practically
> writing all the phpdoc for you, it also does code analysis for stuff
> like variables that are never used, and code that is never executed. I
> think if we're concerned about "bloat" we could stand to drop the
> function or two that never gets used.
>
>  
Functions might not be used in the core, but might provide useful API
functions to plugins and thus need to remain.

--
Rob Miller
http://robm.me.uk/ | http://kantian.co.uk/

_______________________________________________
wp-hackers mailing list
[hidden email]
http://lists.automattic.com/mailman/listinfo/wp-hackers