More concrete information in documentation.

[NetzwergX]

First of all, i'm very pleased with the effort you take to write good documentation for WCF 2.0, it mostly helps much.

But, as always, there is a but:
The documentation is sometimes very generic and says nothing really helpful. I'll give you one example:

In the Request class in wcf\system\request there is a method getPageType(). What this method does is very obvoius from it's name alone. And so the documentation says "Returns the page type of this request." and specifies the return type as a string. Oh wow. that much i can guess. But i do not get any information on what i can really expect as return value. Will it be "Form" for a form, or "form". So i either have to dig through tons of other source code or, what i did, simple make a var_dump to get that value. That is somewhat annoying. it would be much, much simpler, if the documentation simply said "Returns the page type of this request. Return values can be one of 'page', 'form' or 'action'". Thats one sentence of documentation more, but it saves a lot of time. i understand that you can not always give such concrete information about the return value, but in other cases including example values in the documentation is helpful, too. For example, getPageName() from the same class could benefit from a sentence like "For example, when index.php/Index/ is requested, the return value of this method is 'Index'" and so on. Such things would really smooth out the whole development process. Maybe you should take a look at the javadocs from Oracle, they are a good example for those kind of things.

Other then including information about the return type in the method description you could add information about the return type in the @return statement of the phpdoc. it is definied as following @return (object objectname|type) [$varname] [description] (cf. http://www.phpdoc.de/kongress/return.html). So a thing like @return string $this->pageType One of 'page', 'form' or 'action' is equally valid and probably even better practice then putting information about the return type in the method description.

Since you guys wrote the software i understand that its obvious for you what return value is to be expected here, but not for others (especially when you start digging into WCF 2.0 after it has been released and did not have the time to familiarize yourself with it during the development time here on GitHub).

So, tl;dr-version: Please try to keep the documentation more concrete and don't use generic statements that do not say more then the method name itself. Especially documentation of expected return types is sometimes a little undervalued (and sometimes also valid values for method parameters could be documented better).

Do not get me wrong: The documentation of WCF 2.0 is really good compared to many other php scripts / software, but, at some points, it could even be better.

[TimWolla]

I'd leave the varname out in @return as it does not tell anything the users has to know. But: +1

[NetzwergX]

You're right, on a second look i'll leave it out, too (at least in the example cases, there might be some cases were exposing it might be helpful).