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
_______________________________________________
wp-docs mailing list
[email protected]
http://lists.automattic.com/mailman/listinfo/wp-docs
