[wp-docs] Inline Documentation -- Better Quality Assurance

[Jacob Santos]

It was expressed to me to continue the effort from how it helped others. 
However, I mean, it was a few months after that thread that I finally 
took it up again. I was able to complete majority of the remaining files 
in September and the rest in October. I had help, which increased my 
motivation for working on it. Scott H. completed the bulk of a really 
difficult to document functions in formatting.php. It got to the point 
where I was completing almost a file a day.

The WordPress administration Library still needs to be documented, but 
the majority of what plugin and theme developers work with have been 
documented. It will help coders modifying the WordPress Admin by 
creating patches or whatever to have it documented, but I have no 
motivation to document it. If it isn't documented by Spring or Summer 
next year, then I'll probably finish it.

I did leave an update which stated that the effort was finally a 
success. Other contributors are mostly maintaining the inline 
documentation now. It is nice that you are using it for the codex. That 
was one of the intentions with no including more examples in the code.

Actually, the inline documentation does also include a link to the 
codex, where applicable, for more examples and details. I think that 
once you get more completed, I'll go through and create a patch linking 
more of the functions to the codex. It was my hope that the function 
reference would link back to the codex and the codex would link to the 
function reference. However the official phpdoc site is FUBAR at the moment.

Jacob Santos

Charles K. Clarkson wrote:
> Hello,
>
> Before adding my own two cents to this list, I read about a year's 
> worth of archived posts. I remember being particularly struck by a 
> message from Jacob Santos about the failure of his Inline 
> Documentation project. It was really disheartening to hear someone had 
> gone through such a Herculean effort and had been met with a feeling 
> of such despair.
>
> Today, I was reading the Version_2.7 page [1] and I ran across this 
> section [2]:
>
>
> Inline Documentation
>
> The WordPress 2.7 has almost every file fully documented with phpdoc 
> type inline documentation. This includes most of the files with file 
> level phpdoc blocks. The functions have the parameters accepted type 
> documented with descriptions. The functions also have short 
> descriptions and many functions have long descriptions.
>
> This should improve the support and limit the questions newcomers have 
> about the WordPress library. It is also along the goal of better 
> quality assurance.
>
>
>
> Jacob, it seems to me that you changed a mind or two about the 
> importance of Inline Documentation. I know my project will be a lot 
> easier due to your efforts.
>
>
> Thanks for not giving up.
>
>
> [1] http://codex.wordpress.org/Version_2.7
> [2] http://codex.wordpress.org/Version_2.7#Inline_Documentation
>
>
> HTH,
>
> Charles Clarkson