Call for help: Documentation

classic Classic list List threaded Threaded
64 messages Options
1234
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

robertbasic
I have this whole day just for the docs, so, I'd like to ask what's
broken with the Zend\Loader and Zend\ModuleManager documentations?

Thanks!
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

robertbasic
In reply to this post by weierophinney
While I wait for info on Loader and ModuleManager, picking up Zend\Mime.
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

robertbasic
In reply to this post by weierophinney
Am I boring already? :)

Zend\Soap. :)
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

weierophinney
Administrator
In reply to this post by BullfrogBlues
-- Gerry - <[hidden email]> wrote
(on Monday, 01 October 2012, 04:14 AM +0100):
> A couple of quick questions on PHPDocs:
>
> * Should `@return void` be required or be removed, is it necessary?

In constructors, it should be removed (since you can't really return
anything from a constructor in a meaningful fashion).

Elsewhere, it should be retained, to indicate that the null return value
is known and intended.

> * Should all fluent interfaces be commented `@return WhateverObject Provides
> fluent interface`?

The "Provides fluent interface" verbiage isn't really necessary.

> * What are the standards, if any, with `@triggers`?

Still TBD. The problem right now is determining how to indicate a
combination of event type and parameters passed.

> * Should specifying the method name at the top of a method PHPDoc be
>               discouraged, or required? It's pretty much redundant isn't it?

Yeah, method name is redundant and pointless. It should be a short
descriptor in plain english indicating the purpose.

--
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
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

weierophinney
Administrator
In reply to this post by robertbasic
-- Robert Basic <[hidden email]> wrote
(on Monday, 01 October 2012, 09:41 AM +0200):
> I have this whole day just for the docs, so, I'd like to ask what's
> broken with the Zend\Loader and Zend\ModuleManager documentations?

IIRC, the Loader docs still reference some classes that are no longer
used and/or removed; also, I'm not sure the ModuleAutoloader is
documented.

For the ModuleManager, IIRC, there are missing docs; ask Evan on IRC,
though, for more details.

--
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
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

Adam Lundrigan
I'll update Zend\Http docs to reflect API changes.  If that's already in progress, speak up and stop me :)

--
Adam Lundrigan, B.Sc, ZCE
[hidden email]


On Mon, Oct 1, 2012 at 11:59 AM, Matthew Weier O'Phinney <[hidden email]> wrote:
-- Robert Basic <[hidden email]> wrote
(on Monday, 01 October 2012, 09:41 AM +0200):
> I have this whole day just for the docs, so, I'd like to ask what's
> broken with the Zend\Loader and Zend\ModuleManager documentations?

IIRC, the Loader docs still reference some classes that are no longer
used and/or removed; also, I'm not sure the ModuleAutoloader is
documented.

For the ModuleManager, IIRC, there are missing docs; ask Evan on IRC,
though, for more details.

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

Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

Ralf Eggert
In reply to this post by weierophinney
Hi,

could someone update this file please?

https://github.com/zendframework/zf2-documentation/blob/master/TODO.md

Since Robert "the Documentator" Basic and others worked on the docs in
the last days it would be nice to see the current status.

Regards,

Ralf
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

robertbasic

Hey Ralf,

I've already sent a PR to update the TODO, just waiting for it to be merged.

On 3 Oct 2012 23:01, "Ralf Eggert" <[hidden email]> wrote:
Hi,

could someone update this file please?

https://github.com/zendframework/zf2-documentation/blob/master/TODO.md

Since Robert "the Documentator" Basic and others worked on the docs in
the last days it would be nice to see the current status.

Regards,

Ralf
Reply | Threaded
Open this post in threaded view
|

AW: [zf-contributors] Call for help: Documentation

Marc Tempelmeier
In reply to this post by weierophinney
Actually he is called Robert "the docu beast" Basic atm ;)


-----Ursprüngliche Nachricht-----
Von: Ralf Eggert [mailto:[hidden email]]
Gesendet: Mittwoch, 3. Oktober 2012 23:01
An: [hidden email]
Betreff: Re: [zf-contributors] Call for help: Documentation

Hi,

could someone update this file please?

https://github.com/zendframework/zf2-documentation/blob/master/TODO.md

Since Robert "the Documentator" Basic and others worked on the docs in
the last days it would be nice to see the current status.

Regards,

Ralf
Reply | Threaded
Open this post in threaded view
|

AW: [zf-contributors] Call for help: Documentation

Marc Tempelmeier
In reply to this post by weierophinney
Hi,

an idea which came up while there was a little debate about blog posts in the irc channel.

How you all like a section in the docs where we collect urls to blog posts
which describe a specific component in detail?

The "problem" I see at the moment is that a lot of people write
blog posts but if one don´t follow that blog he/she probably won´t ever read it.

As example I have my own co workers who demand a good documentation, they will never care about the people who programmed, nor will read their blogs.
Sadly...

Any comments? :)

Greetings

Marc (G0re)



-----Ursprüngliche Nachricht-----
Von: Marc Tempelmeier [mailto:[hidden email]]
Gesendet: Donnerstag, 4. Oktober 2012 09:02
An: [hidden email]
Betreff: AW: [zf-contributors] Call for help: Documentation

Actually he is called Robert "the docu beast" Basic atm ;)


-----Ursprüngliche Nachricht-----
Von: Ralf Eggert [mailto:[hidden email]]
Gesendet: Mittwoch, 3. Oktober 2012 23:01
An: [hidden email]
Betreff: Re: [zf-contributors] Call for help: Documentation

Hi,

could someone update this file please?

https://github.com/zendframework/zf2-documentation/blob/master/TODO.md

Since Robert "the Documentator" Basic and others worked on the docs in
the last days it would be nice to see the current status.

Regards,

Ralf
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

weierophinney
Administrator
-- Marc Tempelmeier <[hidden email]> wrote
(on Thursday, 04 October 2012, 10:28 AM +0200):
> an idea which came up while there was a little debate about blog posts
> in the irc channel.
>
> How you all like a section in the docs where we collect urls to blog posts
> which describe a specific component in detail?

The problem with this is that people's blogs come and go, and as a
result, the content disappears over time.

The approach I've been taking is asking authors of particularly good
blog posts to submit the content to the manual itself. They then become
associated as an author, and have increased ownership and visibility in
the project.

> The "problem" I see at the moment is that a lot of people write blog
> posts but if one don´t follow that blog he/she probably won´t ever
> read it.
>
> As example I have my own co workers who demand a good documentation,
> they will never care about the people who programmed, nor will read
> their blogs.  Sadly...

I'd say this is a separate problem, and one we're addressing initially
at http://framework.zend.com/participate/blogs -- if you want to see
your blog or that of somebody else on there, submit a PR against the
zf-web repo to add it.

Long term, I'd like to write a "planet-zf" style module for the website,
so that we can aggregate new posts and provide a continual RSS feed of
ZF-related content to those interested.


> -----Ursprüngliche Nachricht-----
> Von: Marc Tempelmeier [mailto:[hidden email]]
> Gesendet: Donnerstag, 4. Oktober 2012 09:02
> An: [hidden email]
> Betreff: AW: [zf-contributors] Call for help: Documentation
>
> Actually he is called Robert "the docu beast" Basic atm ;)
>
>
> -----Ursprüngliche Nachricht-----
> Von: Ralf Eggert [mailto:[hidden email]]
> Gesendet: Mittwoch, 3. Oktober 2012 23:01
> An: [hidden email]
> Betreff: Re: [zf-contributors] Call for help: Documentation
>
> Hi,
>
> could someone update this file please?
>
> https://github.com/zendframework/zf2-documentation/blob/master/TODO.md
>
> Since Robert "the Documentator" Basic and others worked on the docs in
> the last days it would be nice to see the current status.
>
> Regards,
>
> Ralf
>

--
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
Reply | Threaded
Open this post in threaded view
|

AW: [zf-contributors] Call for help: Documentation

Marc Tempelmeier
In reply to this post by weierophinney
Oh, did not know the participate -> blogs one.
Maybe we could place it more central, like there http://framework.zend.com/learn?

+1 for the long term solution

Marc

-----Ursprüngliche Nachricht-----
Von: Matthew Weier O'Phinney [mailto:[hidden email]]
Gesendet: Donnerstag, 4. Oktober 2012 15:25
An: [hidden email]
Betreff: Re: [zf-contributors] Call for help: Documentation

-- Marc Tempelmeier <[hidden email]> wrote
(on Thursday, 04 October 2012, 10:28 AM +0200):
> an idea which came up while there was a little debate about blog posts
> in the irc channel.
>
> How you all like a section in the docs where we collect urls to blog posts
> which describe a specific component in detail?

The problem with this is that people's blogs come and go, and as a
result, the content disappears over time.

The approach I've been taking is asking authors of particularly good
blog posts to submit the content to the manual itself. They then become
associated as an author, and have increased ownership and visibility in
the project.

> The "problem" I see at the moment is that a lot of people write blog
> posts but if one don´t follow that blog he/she probably won´t ever
> read it.
>
> As example I have my own co workers who demand a good documentation,
> they will never care about the people who programmed, nor will read
> their blogs.  Sadly...

I'd say this is a separate problem, and one we're addressing initially
at http://framework.zend.com/participate/blogs -- if you want to see
your blog or that of somebody else on there, submit a PR against the
zf-web repo to add it.

Long term, I'd like to write a "planet-zf" style module for the website,
so that we can aggregate new posts and provide a continual RSS feed of
ZF-related content to those interested.


> -----Ursprüngliche Nachricht-----
> Von: Marc Tempelmeier [mailto:[hidden email]]
> Gesendet: Donnerstag, 4. Oktober 2012 09:02
> An: [hidden email]
> Betreff: AW: [zf-contributors] Call for help: Documentation
>
> Actually he is called Robert "the docu beast" Basic atm ;)
>
>
> -----Ursprüngliche Nachricht-----
> Von: Ralf Eggert [mailto:[hidden email]]
> Gesendet: Mittwoch, 3. Oktober 2012 23:01
> An: [hidden email]
> Betreff: Re: [zf-contributors] Call for help: Documentation
>
> Hi,
>
> could someone update this file please?
>
> https://github.com/zendframework/zf2-documentation/blob/master/TODO.md
>
> Since Robert "the Documentator" Basic and others worked on the docs in
> the last days it would be nice to see the current status.
>
> Regards,
>
> Ralf
>

--
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
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

robertbasic
In reply to this post by weierophinney
On 1 October 2012 16:29, Matthew Weier O'Phinney <[hidden email]> wrote:
> -- Robert Basic <[hidden email]> wrote
> (on Monday, 01 October 2012, 09:41 AM +0200):
>> I have this whole day just for the docs, so, I'd like to ask what's
>> broken with the Zend\Loader and Zend\ModuleManager documentations?
>
> IIRC, the Loader docs still reference some classes that are no longer
> used and/or removed; also, I'm not sure the ModuleAutoloader is
> documented.
>

I'm picking up Zend\Loader docs to fix today/tomorrow/over the weekend.
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

Andreas Möller
In reply to this post by Marc Tempelmeier
> The problem with this is that people's blogs come and go, and as a
> result, the content disappears over time.
>
> The approach I've been taking is asking authors of particularly good
> blog posts to submit the content to the manual itself. They then become
> associated as an author, and have increased ownership and visibility in
> the project.

+1

The biggest problem for a newcomer to ZF2 now is that the official documentation is incomplete.
It should be the first place to look for documentation and usage example of ZF2.

I personally find it quite hard to understand components if there's documentation that mixes ZF1 and ZF2 components.


Best regards,

Andreas
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

Dennis Winter
Totally agree, at least in case of the Zend\Cache docs! I've found no description of the single adapters!

I'll try to wrap my head around it on the weekend and extend the docs wherever possible!

So: Zend\Cache is mine! :)

Am 04.10.2012 um 19:03 schrieb Andreas Möller <[hidden email]>:

>> The problem with this is that people's blogs come and go, and as a
>> result, the content disappears over time.
>>
>> The approach I've been taking is asking authors of particularly good
>> blog posts to submit the content to the manual itself. They then become
>> associated as an author, and have increased ownership and visibility in
>> the project.
>
> +1
>
> The biggest problem for a newcomer to ZF2 now is that the official documentation is incomplete.
> It should be the first place to look for documentation and usage example of ZF2.
>
> I personally find it quite hard to understand components if there's documentation that mixes ZF1 and ZF2 components.
>
>
> Best regards,
>
> Andreas
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

robertbasic
On 4 October 2012 19:12, Dennis Winter <[hidden email]> wrote:
> Totally agree, at least in case of the Zend\Cache docs! I've found no description of the single adapters!
>
> I'll try to wrap my head around it on the weekend and extend the docs wherever possible!
>
> So: Zend\Cache is mine! :)

Zend\Cache is being worked on:
https://github.com/zendframework/zf2-documentation/pull/355
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

Dennis Winter
Okay..
Anything relatively easy and zf2-beginner-friendly, that needs to be worked on?

Am 04.10.2012 um 19:29 schrieb Robert Basic <[hidden email]>:

> On 4 October 2012 19:12, Dennis Winter <[hidden email]> wrote:
>> Totally agree, at least in case of the Zend\Cache docs! I've found no description of the single adapters!
>>
>> I'll try to wrap my head around it on the weekend and extend the docs wherever possible!
>>
>> So: Zend\Cache is mine! :)
>
> Zend\Cache is being worked on:
> https://github.com/zendframework/zf2-documentation/pull/355
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

Marc Bennewitz (private)
Hi Dennis,

I really need help on Zend\Cache documentation. The current PR is more a
template with only some very small texts.


On 04.10.2012 19:38, Dennis Winter wrote:

> Okay..
> Anything relatively easy and zf2-beginner-friendly, that needs to be worked on?
>
> Am 04.10.2012 um 19:29 schrieb Robert Basic <[hidden email]>:
>
>> On 4 October 2012 19:12, Dennis Winter <[hidden email]> wrote:
>>> Totally agree, at least in case of the Zend\Cache docs! I've found no description of the single adapters!
>>>
>>> I'll try to wrap my head around it on the weekend and extend the docs wherever possible!
>>>
>>> So: Zend\Cache is mine! :)
>> Zend\Cache is being worked on:
>> https://github.com/zendframework/zf2-documentation/pull/355

Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

robertbasic
In reply to this post by weierophinney
Realised I should probably focus on the important stuff in the docs, so...

Zend\Mvc docs up next.
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

Andreas Möller
While trying to understand what I'm doing, I noticed that there are a lot of methods in the codebase that do not even have a PhpDoc-comment block.

Is this on purpose or shall these be added?


Andreas


1234