Better API documentation (3)

[Del]

Hi all,

I originally posted this to the fw-docs list but got asked to redirect
it here.

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.

Comments?

Del

[Wesley Overdijk]

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:

Hi all,

I originally posted this to the fw-docs list but got asked to redirect it here.

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.

Comments?

Del

[Maks3w]

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

---

De: Wesley Overdijk <[hidden email]>
Para: Del <[hidden email]>
CC: [hidden email]
Enviado: Lunes 17 de septiembre de 2012 8:01
Asunto: Re: [zf-contributors] Better API documentation (3)

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:

Hi all,

I originally posted this to the fw-docs list but got asked to redirect it here.

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.

Comments?

Del

[Wesley Overdijk]

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 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

---

De: Wesley Overdijk <[hidden email]>
Para: Del <[hidden email]>
CC: [hidden email]
Enviado: Lunes 17 de septiembre de 2012 8:01
Asunto: Re: [zf-contributors] Better API documentation (3)

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:

Hi all,

I originally posted this to the fw-docs list but got asked to redirect it here.

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.

Comments?

Del

[Del]

>     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

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.

Del