Poll: Namespace usage in ZF class method signatures

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

Poll: Namespace usage in ZF class method signatures

Ralph Schindler-2
Hey All:

With PHP 5.3, one of the biggest improvements to the language is
namespaces.  ZF 2.0 intends on taking full advantage of namespaces.  One
of the issues that has come up is how namespaces affect namespace and
class naming.  This email is intended to start a discussion on-list of
some ideas and issues we've seen and would like to discuss with the
community.


On Method Signatures--

As developers, with or without the help of tools, we look at method
signatures to fully understand what a method expects.  Many cases in ZF,
we use type hinting to force a specific type on a method.  With
namespaces, a potential issue crops up with the clarity of a method
signature.

Say for example we have a namespace Foo, class Bar, and method baz. Also
assume there is a namesapce called Qux\Garply involved. Here are a
number of ways baz might be written.

<?php

namespace Foo;

class Bar
{
     // this method accepts an instance of itself
     public static function baz(Bar $bar) {}
}

---

<?php

namespace Foo;

class Bar
{
     // this method accepts an instance of itself
     public static function baz(\Foo\Bar $bar) {}
}


---

<?php
// this class has a use statement

namespace Foo;
use Qux\Garply as garp;

class Bar
{
     // this method accepts an instance of Qux\Garply\Bar
     public static function baz(garp\Bar $bar) {}
}

---

<?php

namespace Foo;
use Qux\Garply as garp;

class Bar
{
     // this method accepts an instance of Qux\Garply\Bar
     public static function baz(\Qux\Garply\Bar $bar) {}
}



===

One thing to notice is that if method signatures contain a fully
qualified name (those starting with a \) for type hints, you don't need
to know anything about what namespaces or aliases are in play;
everything you need to know is right in front of you. However, on the
flip side of the coin, fully qualified names are much more verbose,
somewhat defeating the purpose of namespaces and aliasing in the first
place.

When using unqualified names (those not starting with a \), you gain
some readability (names are more brief), but need to know what the
current namespace is, and what aliases were defined in order to resolve
the classname.

(Matthew notes that in his days working with Perl, the situation was
really no different with packages, and the majority of Perl devs used
aliases when referring to classes. This may or may not be relevant to
PHP, however.)

The question is, what is the best practice here?  When looking at code
like this, which do you expect would be easier to understand?

Should library/framework specific code be more expressive using fully
qualified names in method signatures and consequently in docblocks? Or
is using unqualified names just as easy to understand and/or more readable?


What do you think?
-Ralph

Reply | Threaded
Open this post in threaded view
|

Re: Poll: Namespace usage in ZF class method signatures

Stanislav Malyshev
Hi!

> <?php
>
> namespace Foo;
>
> class Bar
> {
> // this method accepts an instance of itself
> public static function baz(Bar $bar) {}
> }

I'm for this one. That's why we started all the thing with namespaces!

> <?php
> // this class has a use statement
>
> namespace Foo;
> use Qux\Garply as garp;
>
> class Bar
> {
> // this method accepts an instance of Qux\Garply\Bar
> public static function baz(garp\Bar $bar) {}
> }

And this one too, though you could "use" whole Qux\Garply\Bar as QGBar
as well :)

> One thing to notice is that if method signatures contain a fully
> qualified name (those starting with a \) for type hints, you don't need
> to know anything about what namespaces or aliases are in play;
> everything you need to know is right in front of you. However, on the

I have faith that Framework developers actually can remember inside
which class and namespace they are :)

> Should library/framework specific code be more expressive using fully
> qualified names in method signatures and consequently in docblocks? Or
> is using unqualified names just as easy to understand and/or more readable?

Docblocks present interesting challenge, if they are used for typing
purposes. I guess there some solution might be needed, but maybe smart
tools can solve it...
--
Stanislav Malyshev, Zend Software Architect
[hidden email]   http://www.zend.com/
(408)253-8829   MSN: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Poll: Namespace usage in ZF class method signatures

akrabat
In reply to this post by Ralph Schindler-2

On 16 Mar 2010, at 06:26, Ralph Schindler wrote:
>
>
> Should library/framework specific code be more expressive using fully qualified names in method signatures and consequently in docblocks? Or is using unqualified names just as easy to understand and/or more readable?

I think that within a component, aliasing to the component should be used as you know where you are. If other components are used, then fully qualified names should be used for clarity.

Regards,

Rob...
Reply | Threaded
Open this post in threaded view
|

Re: Poll: Namespace usage in ZF class method signatures

Giorgio Sironi
In reply to this post by Stanislav Malyshev
On Tue, Mar 16, 2010 at 8:21 AM, Stanislav Malyshev <[hidden email]> wrote:

>> <?php
>>
>> namespace Foo;
>>
>> class Bar
>> {
>> // this method accepts an instance of itself
>> public static function baz(Bar $bar) {}
>> }
>
> I'm for this one. That's why we started all the thing with namespaces!

+1. Any other signature defeats the purpose of namespaces.

--
Giorgio Sironi
Piccolo Principe & Web Engineer
http://giorgiosironi.blogspot.com
http://twitter.com/giorgiosironi

Reply | Threaded
Open this post in threaded view
|

Re: Poll: Namespace usage in ZF class method signatures

Benjamin Eberlei-2
In reply to this post by akrabat

I disagree with FQN for other packages. Its very verbose and the importing
is pretty much why we want to port to namespaces in the first place.

My argument for importing all classes is easy: You have a central place
where all dependencies of a class are listed. This is a very powerful
concept to see classes that have too much dependencies or see what
dependencies are required at all.

Plus IDEs make it easy to see where a class was imported from.

greetings,
Benjamin

On Tue, 16 Mar 2010 09:35:28 +0000, Rob Allen <[hidden email]> wrote:
> On 16 Mar 2010, at 06:26, Ralph Schindler wrote:
>>
>>
>> Should library/framework specific code be more expressive using fully
>> qualified names in method signatures and consequently in docblocks? Or
is
>> using unqualified names just as easy to understand and/or more
readable?
>
> I think that within a component, aliasing to the component should be
used
> as you know where you are. If other components are used, then fully
> qualified names should be used for clarity.
>
> Regards,
>
> Rob...

Reply | Threaded
Open this post in threaded view
|

Re: Poll: Namespace usage in ZF class method signatures

weierophinney
Administrator
-- Benjamin Eberlei <[hidden email]> wrote
(on Tuesday, 16 March 2010, 11:25 AM +0100):
> I disagree with FQN for other packages. Its very verbose and the importing
> is pretty much why we want to port to namespaces in the first place.

Well said -- +1.

> My argument for importing all classes is easy: You have a central place
> where all dependencies of a class are listed. This is a very powerful
> concept to see classes that have too much dependencies or see what
> dependencies are required at all.

Exactly.

> Plus IDEs make it easy to see where a class was imported from.
>
> greetings,
> Benjamin
>
> On Tue, 16 Mar 2010 09:35:28 +0000, Rob Allen <[hidden email]> wrote:
> > On 16 Mar 2010, at 06:26, Ralph Schindler wrote:
> >>
> >>
> >> Should library/framework specific code be more expressive using fully
> >> qualified names in method signatures and consequently in docblocks? Or
> is
> >> using unqualified names just as easy to understand and/or more
> readable?
> >
> > I think that within a component, aliasing to the component should be
> used
> > as you know where you are. If other components are used, then fully
> > qualified names should be used for clarity.

--
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: Poll: Namespace usage in ZF class method signatures

A.J. Brown-3
Again I'm in agreement here.  That's how all other namespaced languages write their signatures, so why change that?


On Tue, Mar 16, 2010 at 7:59 AM, Matthew Weier O'Phinney <[hidden email]> wrote:
-- Benjamin Eberlei <[hidden email]> wrote
(on Tuesday, 16 March 2010, 11:25 AM +0100):
> I disagree with FQN for other packages. Its very verbose and the importing
> is pretty much why we want to port to namespaces in the first place.

Well said -- +1.

> My argument for importing all classes is easy: You have a central place
> where all dependencies of a class are listed. This is a very powerful
> concept to see classes that have too much dependencies or see what
> dependencies are required at all.

Exactly.

> Plus IDEs make it easy to see where a class was imported from.
>
> greetings,
> Benjamin
>
> On Tue, 16 Mar 2010 09:35:28 +0000, Rob Allen <[hidden email]> wrote:
> > On 16 Mar 2010, at 06:26, Ralph Schindler wrote:
> >>
> >>
> >> Should library/framework specific code be more expressive using fully
> >> qualified names in method signatures and consequently in docblocks? Or
> is
> >> using unqualified names just as easy to understand and/or more
> readable?
> >
> > I think that within a component, aliasing to the component should be
> used
> > as you know where you are. If other components are used, then fully
> > qualified names should be used for clarity.

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



--
A.J. Brown
Software Engineer, ZCE
blog : http://ajbrown.org
talk  : (937) 540-0099
chat : IntypicaAJ
Reply | Threaded
Open this post in threaded view
|

Re: Poll: Namespace usage in ZF class method signatures

Ralph Schindler-2
In reply to this post by Stanislav Malyshev
Response inline..

>> <?php
>> // this class has a use statement
>>
>> namespace Foo;
>> use Qux\Garply as garp;
>>
>> class Bar
>> {
>> // this method accepts an instance of Qux\Garply\Bar
>> public static function baz(garp\Bar $bar) {}
>> }
>
> And this one too, though you could "use" whole Qux\Garply\Bar as QGBar
> as well :)

This is actually pretty close to my point.

It's clear to people consuming Zend Framework classes that Bar inside
the method signature means Foo\Bar.  The question comes in when people
are consuming a class that has outside dependencies (like the example
above).

How is a developer suppose to know what the QGBar alias is short for?
Moreover, if we are to use alias in method signatures, what kind of
naming convention should be in play?

Additionally, do we restrict it to importing full namespaces? Or would
we allow importing of single classes?  Do we allow importing an aliased
class into a File and use that inside a method signature?

Imagine this:

<?php
namespace Zend\Some\NS;
use \ArrayObject as Container;

class Foo
{
    public function doSomething(Container $c);
}
?>

This is totally possible, and you could argue that its a superb use of
namespaces.  Some might argue that it borders on runkit functionality
(the ability to alias names bit). How is a developer suppose to know
simply by looking at the method signature that he just needs to supply
an ArrayObject?

Do we simply rely on tools to tell us what Container really means?

I totally agree with using "namespace resolved names" for method
signatures, but I am skeptical on whether using "use resolved names" is
going to produce easy to use APIs.



>> One thing to notice is that if method signatures contain a fully
>> qualified name (those starting with a \) for type hints, you don't need
>> to know anything about what namespaces or aliases are in play;
>> everything you need to know is right in front of you. However, on the
>
> I have faith that Framework developers actually can remember inside
> which class and namespace they are :)


By "Framework developers" do you mean people writing ZF code? or people
consuming ZF code?  I actually don't care about the burden put on people
writing code for ZF, b/c you only need to write it once.  It's the
burden put on the consumers of the ZF library of code that I feel is
more important.


>> Should library/framework specific code be more expressive using fully
>> qualified names in method signatures and consequently in docblocks? Or
>> is using unqualified names just as easy to understand and/or more
>> readable?
>
> Docblocks present interesting challenge, if they are used for typing
> purposes. I guess there some solution might be needed, but maybe smart
> tools can solve it...

I am guessing that docblock class names should probably be using the
same namespace and use rule resolution that classes use.

-ralph

Reply | Threaded
Open this post in threaded view
|

Re: Poll: Namespace usage in ZF class method signatures

Eric Clemmons
I too prefer to not have shorthand assignments using "AS".  You can dig through the Dojo codebase and see all sorts of "d., dc., dq., etc." shorthand that ultimately is more confusing, even though it's concise.

There's a balance between having a wall of text because of verbose names and obfuscating code via shorthand.  We already know the problems with nondescript variable names.  Let's not fall into the same bad practices because we have a new toy to play with (namespaces).


On Mar 16, 2010, at 2:26 PM, Ralph Schindler wrote:

> Response inline..
>
>>> <?php
>>> // this class has a use statement
>>>
>>> namespace Foo;
>>> use Qux\Garply as garp;
>>>
>>> class Bar
>>> {
>>> // this method accepts an instance of Qux\Garply\Bar
>>> public static function baz(garp\Bar $bar) {}
>>> }
>> And this one too, though you could "use" whole Qux\Garply\Bar as QGBar as well :)
>
> This is actually pretty close to my point.
>
> It's clear to people consuming Zend Framework classes that Bar inside the method signature means Foo\Bar.  The question comes in when people are consuming a class that has outside dependencies (like the example above).
>
> How is a developer suppose to know what the QGBar alias is short for? Moreover, if we are to use alias in method signatures, what kind of naming convention should be in play?
>
> Additionally, do we restrict it to importing full namespaces? Or would we allow importing of single classes?  Do we allow importing an aliased class into a File and use that inside a method signature?
>
> Imagine this:
>
> <?php
> namespace Zend\Some\NS;
> use \ArrayObject as Container;
>
> class Foo
> {
>   public function doSomething(Container $c);
> }
> ?>
>
> This is totally possible, and you could argue that its a superb use of namespaces.  Some might argue that it borders on runkit functionality (the ability to alias names bit). How is a developer suppose to know simply by looking at the method signature that he just needs to supply an ArrayObject?
>
> Do we simply rely on tools to tell us what Container really means?
>
> I totally agree with using "namespace resolved names" for method signatures, but I am skeptical on whether using "use resolved names" is going to produce easy to use APIs.
>
>
>
>>> One thing to notice is that if method signatures contain a fully
>>> qualified name (those starting with a \) for type hints, you don't need
>>> to know anything about what namespaces or aliases are in play;
>>> everything you need to know is right in front of you. However, on the
>> I have faith that Framework developers actually can remember inside which class and namespace they are :)
>
>
> By "Framework developers" do you mean people writing ZF code? or people consuming ZF code?  I actually don't care about the burden put on people writing code for ZF, b/c you only need to write it once.  It's the burden put on the consumers of the ZF library of code that I feel is more important.
>
>
>>> Should library/framework specific code be more expressive using fully
>>> qualified names in method signatures and consequently in docblocks? Or
>>> is using unqualified names just as easy to understand and/or more readable?
>> Docblocks present interesting challenge, if they are used for typing purposes. I guess there some solution might be needed, but maybe smart tools can solve it...
>
> I am guessing that docblock class names should probably be using the same namespace and use rule resolution that classes use.
>
> -ralph

Reply | Threaded
Open this post in threaded view
|

Re: Poll: Namespace usage in ZF class method signatures

Tommy Smith
Excellent (excellent) point Eric!

On Tue, Mar 16, 2010 at 1:38 PM, Eric Clemmons <[hidden email]> wrote:
I too prefer to not have shorthand assignments using "AS".  You can dig through the Dojo codebase and see all sorts of "d., dc., dq., etc." shorthand that ultimately is more confusing, even though it's concise.

There's a balance between having a wall of text because of verbose names and obfuscating code via shorthand.  We already know the problems with nondescript variable names.  Let's not fall into the same bad practices because we have a new toy to play with (namespaces).


On Mar 16, 2010, at 2:26 PM, Ralph Schindler wrote:

> Response inline..
>
>>> <?php
>>> // this class has a use statement
>>>
>>> namespace Foo;
>>> use Qux\Garply as garp;
>>>
>>> class Bar
>>> {
>>> // this method accepts an instance of Qux\Garply\Bar
>>> public static function baz(garp\Bar $bar) {}
>>> }
>> And this one too, though you could "use" whole Qux\Garply\Bar as QGBar as well :)
>
> This is actually pretty close to my point.
>
> It's clear to people consuming Zend Framework classes that Bar inside the method signature means Foo\Bar.  The question comes in when people are consuming a class that has outside dependencies (like the example above).
>
> How is a developer suppose to know what the QGBar alias is short for? Moreover, if we are to use alias in method signatures, what kind of naming convention should be in play?
>
> Additionally, do we restrict it to importing full namespaces? Or would we allow importing of single classes?  Do we allow importing an aliased class into a File and use that inside a method signature?
>
> Imagine this:
>
> <?php
> namespace Zend\Some\NS;
> use \ArrayObject as Container;
>
> class Foo
> {
>   public function doSomething(Container $c);
> }
> ?>
>
> This is totally possible, and you could argue that its a superb use of namespaces.  Some might argue that it borders on runkit functionality (the ability to alias names bit). How is a developer suppose to know simply by looking at the method signature that he just needs to supply an ArrayObject?
>
> Do we simply rely on tools to tell us what Container really means?
>
> I totally agree with using "namespace resolved names" for method signatures, but I am skeptical on whether using "use resolved names" is going to produce easy to use APIs.
>
>
>
>>> One thing to notice is that if method signatures contain a fully
>>> qualified name (those starting with a \) for type hints, you don't need
>>> to know anything about what namespaces or aliases are in play;
>>> everything you need to know is right in front of you. However, on the
>> I have faith that Framework developers actually can remember inside which class and namespace they are :)
>
>
> By "Framework developers" do you mean people writing ZF code? or people consuming ZF code?  I actually don't care about the burden put on people writing code for ZF, b/c you only need to write it once.  It's the burden put on the consumers of the ZF library of code that I feel is more important.
>
>
>>> Should library/framework specific code be more expressive using fully
>>> qualified names in method signatures and consequently in docblocks? Or
>>> is using unqualified names just as easy to understand and/or more readable?
>> Docblocks present interesting challenge, if they are used for typing purposes. I guess there some solution might be needed, but maybe smart tools can solve it...
>
> I am guessing that docblock class names should probably be using the same namespace and use rule resolution that classes use.
>
> -ralph


Reply | Threaded
Open this post in threaded view
|

Re: Poll: Namespace usage in ZF class method signatures

weierophinney
Administrator
In reply to this post by Ralph Schindler-2
-- Ralph Schindler <[hidden email]> wrote
(on Tuesday, 16 March 2010, 02:26 PM -0500):

> Response inline..
>
> > > <?php
> > > // this class has a use statement
> > >
> > > namespace Foo;
> > > use Qux\Garply as garp;
> > >
> > > class Bar
> > > {
> > > // this method accepts an instance of Qux\Garply\Bar
> > > public static function baz(garp\Bar $bar) {}
> > > }
> >
> > And this one too, though you could "use" whole Qux\Garply\Bar as
> > QGBar as well :)
>
> This is actually pretty close to my point.
>
> It's clear to people consuming Zend Framework classes that Bar
> inside the method signature means Foo\Bar.  The question comes in
> when people are consuming a class that has outside dependencies
> (like the example above).

I see no issue with the example above -- the class in the typehint is
namespaced, and there's a clear alias defined at the top of the file...

> How is a developer suppose to know what the QGBar alias is short
> for?

Umm... because there's an alias defined.

> Moreover, if we are to use alias in method signatures, what
> kind of naming convention should be in play?

I think this is the only real relevant point. The aliases should be
clear -- in most cases, if aliasing a namespace, use the namespace (as
it is likely the component name); if importing a single class, use the
classname, or give the classname context based on the component
namespace it lives in.

> Additionally, do we restrict it to importing full namespaces? Or
> would we allow importing of single classes?  

You should import what you need, plain and simple.

Some potential guidelines:

 * If the class is used only once, it may make as much or more sense to
   simply use the fully qualified name -- with the caveat that if it's
   stupidly long, create a meaningful, short alias.

 * When importing a class, you may need to suffix with the component
   and/or subcomponent namespace:

     use \Zend\Filter\Int as IntFilter;
     use \Zend\Db\Adapter\Mysql as MysqlDbAdapter;

 * When importing a namespace, simply use the final segment of the
   namespace, unless it may need context from the component:

     use \Zend\Filter;
     use \Zend\Db\Adapter as DbAdapter;

     $filter  = new Filter\Int();
     $adapter = new DbAdapter\Mysql();

   In the above example, I chose "DbAdapter" as the alias so that
   there's not confusion with other adapters or plugins being used.

> Do we allow importing an aliased class into a File and use that inside
> a method signature?

As long as a meaningful alias has been used, and it clearly doesn't
conflict with classes in the namespace, I don't see why not. That said,
I'd recommend aliasing namespaces over classes in most cases.

> Imagine this:
>
> <?php
> namespace Zend\Some\NS;
> use \ArrayObject as Container;
>
> class Foo
> {
>    public function doSomething(Container $c);

I'd call that an ambiguous and unnecessary alias, to be honest. It's
renaming for the sake of renaming, which will cause confusion.

> }
> ?>
>
> This is totally possible, and you could argue that its a superb use
> of namespaces.  Some might argue that it borders on runkit
> functionality (the ability to alias names bit). How is a developer
> suppose to know simply by looking at the method signature that he
> just needs to supply an ArrayObject?

See my note above -- I think that sort of renaming shouldn't happen, and
should be discouraged. It causes ambiguity and confusion.

> Do we simply rely on tools to tell us what Container really means?
>
> I totally agree with using "namespace resolved names" for method
> signatures, but I am skeptical on whether using "use resolved names"
> is going to produce easy to use APIs.
>
>
>
> > > One thing to notice is that if method signatures contain a fully
> > > qualified name (those starting with a \) for type hints, you don't need
> > > to know anything about what namespaces or aliases are in play;
> > > everything you need to know is right in front of you. However, on the
> >
> > I have faith that Framework developers actually can remember
> > inside which class and namespace they are :)
>
>
> By "Framework developers" do you mean people writing ZF code? or
> people consuming ZF code?  I actually don't care about the burden
> put on people writing code for ZF, b/c you only need to write it
> once.  It's the burden put on the consumers of the ZF library of
> code that I feel is more important.

Then it becomes a documentation issue for the ZF and PHP communities,
educating users as to how namespaces work. :)

> > > Should library/framework specific code be more expressive using fully
> > > qualified names in method signatures and consequently in docblocks? Or
> > > is using unqualified names just as easy to understand and/or
> > > more readable?
> >
> > Docblocks present interesting challenge, if they are used for
> > typing purposes. I guess there some solution might be needed, but
> > maybe smart tools can solve it...
>
> I am guessing that docblock class names should probably be using the
> same namespace and use rule resolution that classes use.

That would be my preference.

--
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: Poll: Namespace usage in ZF class method signatures

Stanislav Malyshev
In reply to this post by Stanislav Malyshev
Hi!

> How is a developer suppose to know what the QGBar alias is short for?
> Moreover, if we are to use alias in method signatures, what kind of
> naming convention should be in play?

I guess it has to be either descriptive or generic enough, depending on
what developer actually has to know. E.g., if you are working with
Zend_Service_Goohoo_AwesomeService, than Request is probably
Zend_Service_Goohoo_AwesomeService_Request, and Response is the
respective response (I'm using current 1.x class name notation for
clarity here). Usually if you know what class you need, you'll find good
name for it.

> Additionally, do we restrict it to importing full namespaces? Or would
> we allow importing of single classes? Do we allow importing an aliased
> class into a File and use that inside a method signature?
>
> Imagine this:
>
> <?php
> namespace Zend\Some\NS;
> use \ArrayObject as Container;
>
> class Foo
> {
> public function doSomething(Container $c);
> }

I would avoid this in framework code, though in user code it's maybe
legitimate, and you can play with what Container actually is. Since in
ZF code there's no way to play with it, I'd probably leave \ArrayObject
alone. If you have some long and foreign object, like using
Zend\Http\Client\Adapter\Socket in some other class, you could call it
Socket or HttpSocket or even Connection. Since the name is local, you
don't have to bother to find a name that is good for everywhere - it can
be read in the context of the local code.

>> I have faith that Framework developers actually can remember inside
>> which class and namespace they are :)
>
> By "Framework developers" do you mean people writing ZF code? or people
> consuming ZF code? I actually dont care about the burdon put on people
> writing code for ZF, b/c you only need to write it once. It's the burden
> put on the consumers of the library that I feel is more important.

I mean the people that read/write ZF code. If you just consume the API
and look in the manual, the manual probably would explain to you what
you need to do and what to pass. We may have to find a way to document
it properly - i.e. in the manual when we refer to some class will we
always use full name or sometimes we can say "AwesomeService::execute()
accepts Request object and returns Response object" and have link or
floating text or something like that which would actually have full
names of Request and Response? It's a good topic to explore.

> I am guessing that docblock class names should probably be using the
> same namespace and use rule resolution that classes use.

The problem is that right now the docblocks are opaque to the engine and
namespace/use info is not kept anywhere in the docblock, so if some code
parses it it might need some additional help there.
--
Stanislav Malyshev, Zend Software Architect
[hidden email]   http://www.zend.com/
(408)253-8829   MSN: [hidden email]