[wp-hackers] Inline Documentation Effort Updates

[Stephane Daury]

Jacob (and helpers)

Late on this, but I wanted to say:
- sorry I totally missed your call for help back then (prob' had my  
head deep in WPhone with Viper and Zamoose at the time)...
- I had indeed noticed the nice coverage in trunk and wanted to say  
thanks and good job. It's looking great.

Stephane Daury





On Sep 26, 2008, at 0:35, Jacob Santos wrote:

> Ryan McCue wrote:
>> Peter Westwood wrote:
>>
>>> The root of the site is http://phpdoc.ftwr.co.uk/ and it is set to
>>> automattically update every 30 minutes as things change.
>>>
>>
>> *wonders if the mispelling of "automatically" was on purpose* :-P
>>
>> Also, Jacob, thanks for all your work on this. It's really great to  
>> be
>> able to have developer documentation for the code and it's made  
>> creating
>> plugins, patches and, really, everything much easier. My only  
>> regret is
>> that I wasn't able to help and I apologise for that.
>>
> Oh yeah, Ryan Boren has added http://phpdoc.wordpress.org/trunk/ and http://phpdoc.wordpress.org/tags/2.6.2/ 
>  and I suspect that when 2.7 comes out, that will also be added.  
> Peter Westwood also bought his sites back up for more than just  
> WordPress, which is pretty cool.
>
> I don't want anyone to feel back for not helping. I actually learned  
> a lot and had some fun doing it (well, I wouldn't have put as much  
> effort in it if it wasn't at least a little bit fun). I think it is  
> fine that the community are writing patches that includes inline  
> documentation and I think it is great that the core commit team  
> developers are adding inline documentation for new functions. It is  
> absolutely fantastic, that the majority of the core team is writing  
> inline documentation. That was mostly the whole point of the effort  
> in the first place. The theory was that no one felt like adding  
> inline documentation, because inline documentation didn't exist and  
> if it did exist, then more people will write inline documentation.  
> It appears the theory was correct. I like to feel that I had  
> something to do with it, but I'm sure with the ratio of code to  
> comments, that the core team was already doing so before I started.
>
> The contention I have, has always been quality assurance, which when  
> I joined the community WordPress had very little. Or at least very  
> little that could be seen. That has changed, not because of me, but  
> because of the community and Automattic. I applaud that as a PHP  
> developer, I don't have to feel dirty for using WordPress, when  
> there are supposed "better" developed alternatives out there. You  
> know, with inline documentation and unit tests. WordPress has both  
> of those and as an user of WordPress, I'm very happy of the gains  
> WordPress has made because of the community.
>
> All open source projects have problems with motivating community  
> members to take action. PHP, the language has the same problem.  
> Well, they have more people working on the developer manual of the  
> language than actually writing inline documentation, but I mean they  
> could use more people writing test cases for extensions. There is a  
> long list of people on the http://codex.wordpress.org/Inline_Documentation 
>  to thank that helped out a great deal. Most of them in the past and  
> several in the present. I predict more to come in the future.
>
> As a developer, I also enjoy that I can look at the WordPress source  
> or phpDocumentor sites and get API documentation for WordPress  
> functions. I might have documented a lot of functions, but I'll be  
> damned if I can remember them all. Using PDT, has also gained some  
> enjoyment, since it displays the short description and parameter  
> information (sadly the long description is not shown). I just kind  
> of wished that it existed when I started writing plugins, but at  
> least those that start writing plugins for WordPress 2.7 won't have  
> as hard of a time finding functions.
>
> If anyone wishes to help there is a ticket devoted to the mistakes  
> in the documentation for each milestone, named "Inline documentation  
> corrections..." or search for the keyword "phpdoc" find that ticket  
> and submit the patch. Doesn't matter if it only changes one word or  
> changes the entire function level phpdoc block.
>
> We as a community need to help out with the quality assurance of  
> WordPress, well some of us do. I think what you do, Ryan, is great,  
> so keep doing it. No apology is needed. I'm actually more mad at the  
> early developers for not writing the inline documentation  
> themselves. What it would have saved if the effort gained support in  
> 0.70, 1.0, but it solves nothing blaming those who are gone.
>
> The next step I think is improving the level of testing automation,  
> which is boring, fun, and a larger task to complete than inline  
> documentation. Thankfully, there are already several people working  
> on it already (http://svn.automattic.com/wordpress-tests), so  
> helping with that will also go a long way.
>
> Actually, post-template.php is halfway complete, so I'm pretty sure  
> I'll be finishing that one up before the end of this weekend. I'm  
> still not sure about link-template.php, but it would be a shame to  
> have one file just hanging out there all alone. I'm thinking I might  
> finish it up, but I won't be mad, if someone completes it before I do.
>
> Jacob Santos
> _______________________________________________
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-hackers