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

weierophinney
Administrator
-- Andreas Möller <[hidden email]> wrote
(on Friday, 05 October 2012, 04:41 PM +0200):
> 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?

Feel free to add them. :)

(I've merged a ton of PRs in the past two weeks, and many are doing
exactly that.)

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

packages.zendframework.com is down?

Antoine Hedgecock
In reply to this post by weierophinney
Was trying to get hold of zf1 source code and noticed the site is down, not to sure who is in charge of it.

Best regards
Antoine Hedgecock
Senior developer / Server technician
PMG Media Group AB
[hidden email]
tel: +46707962145

Reply | Threaded
Open this post in threaded view
|

Re: packages.zendframework.com is down?

Marco Pivetta
Hi there,

looks like something is broken on zend's side right now, guess we need to be patient :\

Marco Pivetta

http://twitter.com/Ocramius     

http://marco-pivetta.com    



On 8 October 2012 12:21, Antoine Hedgecock <[hidden email]> wrote:
Was trying to get hold of zf1 source code and noticed the site is down, not to sure who is in charge of it.

Best regards
Antoine Hedgecock
Senior developer / Server technician
PMG Media Group AB
[hidden email]
tel: <a href="tel:%2B46707962145" value="+46707962145">+46707962145


Reply | Threaded
Open this post in threaded view
|

Re: packages.zendframework.com is down?

weierophinney
Administrator
In reply to this post by Antoine Hedgecock
We've been having intermittent during the weekend. I've started
analyzing logs in an attempt to determine what's going on, but so far
haven't been able to isolate the issue. The only thing sticking out is
that we get a message indicating MaxClients has been reached -- but
nothing in the logs indicating a coordinated DoS or SYN flood. Hopefully
we can iron it out soon.

-- Antoine Hedgecock <[hidden email]> wrote
(on Monday, 08 October 2012, 12:21 PM +0200):
> Was trying to get hold of zf1 source code and noticed the site is down, not to sure who is in charge of it.
>
> Best regards
> Antoine Hedgecock
> Senior developer / Server technician
> PMG Media Group AB
> [hidden email]
> tel: +46707962145
>

--
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: packages.zendframework.com is down?

Wesley Overdijk
It's just THAT popular.

On Mon, Oct 8, 2012 at 4:01 PM, Matthew Weier O'Phinney <[hidden email]> wrote:
We've been having intermittent during the weekend. I've started
analyzing logs in an attempt to determine what's going on, but so far
haven't been able to isolate the issue. The only thing sticking out is
that we get a message indicating MaxClients has been reached -- but
nothing in the logs indicating a coordinated DoS or SYN flood. Hopefully
we can iron it out soon.

-- Antoine Hedgecock <[hidden email]> wrote
(on Monday, 08 October 2012, 12:21 PM +0200):
> Was trying to get hold of zf1 source code and noticed the site is down, not to sure who is in charge of it.
>
> Best regards
> Antoine Hedgecock
> Senior developer / Server technician
> PMG Media Group AB
> [hidden email]
> tel: <a href="tel:%2B46707962145" value="+46707962145">+46707962145
>

--
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
Here's a question:

How to refer to Zend Framework 1 and Zend Framework 2 in the
documentation, especially when not talking about a specific version,
but about a "generation" as a whole?

Zend Framework 1.x and Zend Framework 2.x? Zend Framework 1.0 and Zend
Framework 2.0? Zend Framework 1 and Zend Framework 2?

Thank you.
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

robertbasic
In reply to this post by weierophinney
Zend\ModuleManager up next.
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

Andreas Möller
> Zend\ModuleManager up next.

+1


On a separate note: I've wondered when looking around in source code why for the @subpackage tag in class level PhpDoc-comments, packages such as

* Zend_I18n

are mentioned. Shouldn't the package name reflect namespaces, i.e., shouldn't the subpackage be

* Zend\I18n

. . . ?


Best regards,

Andreas
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

robertbasic
On 9 October 2012 13:51, Andreas Möller <[hidden email]> wrote:
>> Zend\ModuleManager up next.
>
> +1

+1? You're working on it too?
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 Tuesday, 09 October 2012, 11:56 AM +0200):
> Here's a question:
>
> How to refer to Zend Framework 1 and Zend Framework 2 in the
> documentation, especially when not talking about a specific version,
> but about a "generation" as a whole?
>
> Zend Framework 1.x and Zend Framework 2.x? Zend Framework 1.0 and Zend
> Framework 2.0? Zend Framework 1 and Zend Framework 2?

I'd argue either Zend Framework 1 or Zend Framework 1.x. The former is
simpler, but might not necessarily connote the entire major version; the
latter feels more correct, but is, of course, more verbose.

1.0 and 2.0 do not make sense, as they represent specific minor
versions, and not the evolution and totality of the entire major
version cycle.

--
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 Andreas Möller
-- Andreas Möller <[hidden email]> wrote
(on Tuesday, 09 October 2012, 01:51 PM +0200):

> On a separate note: I've wondered when looking around in source code
> why for the @subpackage tag in class level PhpDoc-comments, packages
> such as
>
> * Zend_I18n
>
> are mentioned. Shouldn't the package name reflect namespaces, i.e.,
> shouldn't the subpackage be
>
> * Zend\I18n
>
> . . . ?

Originally, it was due to phpDocumentor not being able to process the
namespace separator in package and subpackage names. This may no longer
be an issue; I'll need to check with the phpDocumentor team, however.

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

Andreas Möller

> Originally, it was due to phpDocumentor not being able to process the
> namespace separator in package and subpackage names. This may no longer
> be an issue; I'll need to check with the phpDocumentor team, however.

I have compiled documentation with PhpDocumentor 2 using "\" as a separator for packages and/or sub packages a few weeks ago and it worked well.


Best regards,

Andreas
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

Andreas Möller
In reply to this post by weierophinney

Originally, it was due to phpDocumentor not being able to process the
namespace separator in package and subpackage names. This may no longer
be an issue; I'll need to check with the phpDocumentor team, however.

For reference, see



Best regards,

Andreas
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

Andreas Möller
In reply to this post by weierophinney

Originally, it was due to phpDocumentor not being able to process the
namespace separator in package and subpackage names. This may no longer
be an issue; I'll need to check with the phpDocumentor team, however.

And this:

Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

weierophinney
Administrator
In reply to this post by Andreas Möller
-- Andreas Möller <[hidden email]> wrote
(on Wednesday, 10 October 2012, 07:16 AM +0200):
> > Originally, it was due to phpDocumentor not being able to process the
> > namespace separator in package and subpackage names. This may no longer
> > be an issue; I'll need to check with the phpDocumentor team, however.
>
> I have compiled documentation with PhpDocumentor 2 using "\" as a
> separator for packages and/or sub packages a few weeks ago and it
> worked well.

That suggests we can change it, then.

The question is: should we at this point?

Doing so would touch basically every classfile in the library. Not doing
so simply means we have to remember to use "_" in the package and
subpackage names as new classes are introduced.

Thoughts?

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

Andreas Möller
> That suggests we can change it, then.
>
> The question is: should we at this point?
>
> Doing so would touch basically every classfile in the library. Not doing
> so simply means we have to remember to use "_" in the package and
> subpackage names as new classes are introduced.
>
> Thoughts?

It will be some work to replace all these underscores, but even a ZF2 noob look me could do it - and I would, actually.

However, someone will have to merge in the pull request. And it's probably not going to be a lot of fun going through all these files and check.


Best regards,

Andreas



Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

Andreas Möller
Concerning the possibly existing conventions for specifying values for

* @package
* @subpackage

I have found a number of variations, for example:

@package    Zend\Loader
@subpackage Exception

then

@package    Zend_Cache
@subpackage Zend_Cache_Storage
@subpackage Storage

Shouldn't the naming scheme be consistent (apart from the decision whether to use backslash or underscore)?


Best regards,

Andreas
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

weierophinney
Administrator
-- Andreas Möller <[hidden email]> wrote
(on Thursday, 11 October 2012, 12:06 PM +0200):

> Concerning the possibly existing conventions for specifying values for
>
> * @package
> * @subpackage
>
> I have found a number of variations, for example:
>
> @package    Zend\Loader
> @subpackage Exception
>
> then
>
> @package    Zend_Cache
> @subpackage Zend_Cache_Storage
> @subpackage Storage
>
> Shouldn't the naming scheme be consistent (apart from the decision
> whether to use backslash or underscore)?

Ideally, yes. :)

Package should typically be the component namespace: Zend\Loader or
Zend_Loader (the latter is what we primarily use currently, but is up
for debate, as you've noted!).

Subpackage should be the subpackage name, *without* the parent
namespace:

    Storage (good)
    Zend_Cache_Storage (bad)

If the subpackage is a further subnamespace, that's okay:

    Storage\Adapter
    or
    Storage_Adapter

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

Andreas Möller
>> Shouldn't the naming scheme be consistent (apart from the decision
>> whether to use backslash or underscore)?
>
> Ideally, yes. :)
>
> Package should typically be the component namespace: Zend\Loader or
> Zend_Loader (the latter is what we primarily use currently, but is up
> for debate, as you've noted!).
>
> Subpackage should be the subpackage name, *without* the parent
> namespace:
>
>    Storage (good)
>    Zend_Cache_Storage (bad)
>
> If the subpackage is a further subnamespace, that's okay:
>
>    Storage\Adapter
>    or
>    Storage_Adapter

Shall I go about and change this?


Best regards,

Andreas
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

weierophinney
Administrator
-- Andreas Möller <[hidden email]> wrote
(on Thursday, 11 October 2012, 03:22 PM +0200):

> >> Shouldn't the naming scheme be consistent (apart from the decision
> >> whether to use backslash or underscore)?
> >
> > Ideally, yes. :)
> >
> > Package should typically be the component namespace: Zend\Loader or
> > Zend_Loader (the latter is what we primarily use currently, but is up
> > for debate, as you've noted!).
> >
> > Subpackage should be the subpackage name, *without* the parent
> > namespace:
> >
> >    Storage (good)
> >    Zend_Cache_Storage (bad)
> >
> > If the subpackage is a further subnamespace, that's okay:
> >
> >    Storage\Adapter
> >    or
> >    Storage_Adapter
>
> Shall I go about and change this?

If you have the time and inclination, definitely. :)

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