Better API documentation (2)

[Del]

Hi all,

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

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

--
List: [hidden email]
Info: http://framework.zend.com/archives
Unsubscribe: [hidden email]

[Marco Pivetta]

Hi Del,

Yes, documentation needs some love, but all the people that have been working on producing ZF2's code are kinda swamped right now. If you do Pull Requests, that is already awesome!

Marco Pivetta

http://twitter.com/Ocramius     

http://marco-pivetta.com    

On 14 September 2012 06:24, Del [via Zend Framework Community] <[hidden email]> wrote:

Hi all,

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

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

--
List: [hidden email]
Info: http://framework.zend.com/archives
Unsubscribe: [hidden email]

---

If you reply to this email, your message will be added to the discussion below:

http://zend-framework-community.634137.n4.nabble.com/Better-API-documentation-2-tp4656819.html

To unsubscribe from Zend Framework Community, click here.
NAML

[weierophinney]

-- Del <[hidden email]> wrote
(on Friday, 14 September 2012, 02:23 PM +1000):

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

Several things.

First, you may want to bring this up on the zf-contributors list; not
many folks involved with API docs are on the fw-docs list (it's mainly
about translations).

Second, we have actually favored having examples in the end-user
documentation over the API documentation; the idea is to have the API
documentation document the arguments, return values, and expected
exceptions, with very brief indications of usage. As such, if you could
assist with the end-user documentation, particularly providing examples,
that would be ideal.

Thanks!

--
Matthew Weier O'Phinney
Project Lead            | [hidden email]
Zend Framework          | http://framework.zend.com/
PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc

--
List: [hidden email]
Info: http://framework.zend.com/archives
Unsubscribe: [hidden email]

[Del]

> Several things.
>
> First, you may want to bring this up on the zf-contributors list; not
> many folks involved with API docs are on the fw-docs list (it's mainly
> about translations).

Noted -- I've sent a request to join that list.

> Second, we have actually favored having examples in the end-user
> documentation over the API documentation; the idea is to have the API
> documentation document the arguments, return values, and expected
> exceptions, with very brief indications of usage. As such, if you could
> assist with the end-user documentation, particularly providing examples,
> that would be ideal.

Fine, but the end-user documentation only covers a small subset of the
functions in each class in ZF2, and doesn't comprehensively mention each
attribute.  It's the API documentation that needs to do that, and if an
example is helpful there I think it should be added (or at least
mentioned if it's in the end-user documentation).

I've sent a pull request for zf2-documentation btw, to get PDF
generation to work.  It now does work for me although I had to add some
extra latex packages over and above the Ubuntu base install.  That may
not be the case on other distros.

Del



--
List: [hidden email]
Info: http://framework.zend.com/archives
Unsubscribe: [hidden email]

[Del]

> I've sent a pull request for zf2-documentation btw, to get PDF
> generation to work.  It now does work for me although I had to add some
> extra latex packages over and above the Ubuntu base install.  That may
> not be the case on other distros.

In case anyone's interested in the PDF output from that, it's here:

http://dl.dropbox.com/u/21366000/ZendFramework2.pdf

Del


--
List: [hidden email]
Info: http://framework.zend.com/archives
Unsubscribe: [hidden email]