[wp-hackers] Inline Documentation Effort Updates
wordpress at tekartist.org
Fri Sep 26 13:56:48 GMT 2008
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.
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
>> able to have developer documentation for the code and it's made
>> 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
More information about the wp-hackers