I originally posted this to the fw-docs list but got asked to redirect
I've just joined the mailing list and been searching for some better API
documentation. I picked up the earlier thread from Jan Jakes and the
problem that I see is that the API documentation is too thin.
e.g. a class header that says:
* @category Zend
* @package Zend_Form
... and that's it.
The problem with the main documentation is that it gives a few examples
and leaves you to it. The API documentation should be more
comprehensive, and should list every class and function, which it does,
and give a working example of each. That's not nearly there yet. For
example, I had to do quite a bit of searching to find out the correct
parameters to create a form with both validators and filters using the
form factory class.
So I thought I would start writing some. I have forked the github repo
and cloned that to my drive and I'll start with the classes I have used
and work outwards from there.
I'd say that you're absolutely right when it comes to lack of docs. However, make sure that you're not going to write entire tutorials in docblocks, as that would start to become fairly polluted. In stead, fork the docs: https://github.com/zendframework/zf2-documentation that's where, if I'm right, we put the actual documentation found here: http://framework.zend.com/docs/api/
Thank you for wanting to help. As a last tip, try writing up blog articles, those can make it in the docs as well if they're really good (like Rob's tutorial).
On Mon, Sep 17, 2012 at 6:23 AM, Del <[hidden email]> wrote:
API and Reference Guide are different things
API docs is updated modifying the docblocks in ZF2 PHP Files as Del proposed
Reference guide is updated forking zf2-documentation
For a little description about the class PHPDoc Docblock is a good place for write it
For write an example about how to use the code then Reference Guide is the right place
That's what I mean yeah. Thanks.
On Mon, Sep 17, 2012 at 8:10 AM, Maks3w <[hidden email]> wrote:
> API and Reference Guide are different things
> API docs is updated modifying the docblocks in ZF2 PHP Files as Del
> Reference guide is updated forking zf2-documentation
> For a little description about the class PHPDoc Docblock is a good
> place for write it
> For write an example about how to use the code then Reference Guide
> is the right place
The "little descriptions" about the class, which are currently missing
from the phpdoc, is where I plan to start. Some of that will be
cut-and-paste from the reference documentation, some of that needs to
give a usage description for each public method.
The examples can go in the reference documentation which I have also forked.
However if there are a bunch of different parameters that can be passed
to a class method, e.g. different values for the "type" element of an
object, then they should also go in the API documentation (docblocks).
Currently they aren't anywhere.
e.g. there is nowhere that lists the possible values for
FormElement->type except by reading all of the code. That should be in
the docblocks, in the header where you call the function, or at least
referred to from there if it's in the reference guide.
|Powered by Nabble||Edit this page|