PSR for comments and documentation

[Matīss Roberts Treinis]

Hi. We should really have a PSR or a PSR-3 extension about inline and outline documentation for PHP. For example, docblocks, comments, comment styles, to use or not to use shell style comments and such. I am aware of Phpdocumentator and Javadoc format, but still - it is not a standard or advisory, and is given by vendor. We could work on a bit more specific PSR based on (and in the best case - compatible with) currently used docblock format widely used by community and as a independent advisory standard. Proposal as fallows -

1. Raise discussion and create a outline of comment blocks, requirements for documentation, including, but not limiting to
   
1. File-wide comments
2. Method, function and property comments
3. Class comments
4. Other (for example, inline) comments?
2. Raise discussion and decide how, why, and when to use document-level comments for methods, properties, classes and files.
   
3. Decide how and when to document method and function arguments.
4. Decide what @tags should be used
5. Decide how variable types for function arguments should be chosen and documented. 

At next, we could think about documenting projects in general. 

[Klaus Silveira]

I agree with Matīss. While a standard for documentation is not directly related to technical interoperability between frameworks, it's crucial for maintaining a stable and healthy library environment. If libraries follow the documentation standard, it's easier for frameworks to adopt them, without ruining their own documentation and/or having to adapt the lib docs.

PHPDoc seems to be a good start, but we need to discuss the existing format and available tags.

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To post to this group, send email to php...@googlegroups.com.
To unsubscribe from this group, send email to php-fig+u...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msg/php-fig/-/mzfTCfGqvogJ.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

--
Klaus Silveira
(011) 8564-2492
www.klaussilveira.com

[Matīss Roberts Treinis]

I could only add that if such PSR for documentation would be created, it would be also much easier to create external tools and adapt already existing ones to handle such properly documented advisory, so it would clear out some inconsistencies in the field of automated documentation generation, which at the current point is almost stuck. 

Quite obvious example would be Phpdocumentator itself - it recommends adding tags and such in inline comments and documentation, which, by my personal opinion is just plain wrong. We could think about solving this too by deciding about adaptation of a or creating a way of linking external documentation to inline one in a consistent, clean, way.

Not so much about interoperability between frameworks indeed, but would solve some confusion in the field. 

[Mike van Riel]

Dear Group,

At phpDocumentor we have already started to do the grunt work of
describing the current
state of affairs and even took a stab at some improvements that we
consider to be viable
for the PHPDoc standard to continue.

Please note that this is a very technical document and is not yet
finished, as such we have
refrained from officially proposing it, and thus opening for
discussion, until the grunt work
was finished and a solid basis for discussion was present.

You can find the working draft in our repository:
https://github.com/phpDocumentor/phpDocumentor2/blob/develop/docs/PSR.md

Please consider this document incomplete as of yet, Chuck Burgess and
I are still working
on adding the technical details.

> --
> You received this message because you are subscribed to the Google Groups
> "PHP Framework Interoperability Group" group.
> To post to this group, send email to php...@googlegroups.com.
> To unsubscribe from this group, send email to
> php-fig+u...@googlegroups.com.
> To view this discussion on the web visit

> https://groups.google.com/d/msg/php-fig/-/4X-hnmlYfE4J.

[Matīss Roberts Treinis]

Greetings. 

By my opinion, changes to or replacement to PHPDoc should not be made nor implemented by a single vendor, what phpDocumentator is.

Crude example is already section 5.2 of particular PHPDocumentator PSR - it already suggests Markdown in long description, which will create "bloat" as it is currently with code documented in a way using HTML tags in a long description. Same with a code examples. 

This is a practice upon which discussion should be raised upon. By my opinion, long descriptions as such should not be present in inline documentation at all, as because it, by my opinion, is not reasonably possible to properly document anything by the means of injecting code samples and such directly into a source code files. It will create "bloat" where documentation block for a short function will end up being twice the length of a function.

We should come up with a better way to do this instead. For example, as mentioned earlier - creating ability to link inline comments to subsequent portions of external documentation or another way. 

2012/9/30 Mike van Riel <draco...@gmail.com>

[Mike van Riel]

Of course you are entitled to your opinion but please consider that
your preference should
be captured in a Coding Standard and not in the PHPDoc Standard.

The PHPDoc Standard tries to enable a wide range of developers to
write inline documentation
as they see fit. Whether you want to use short descriptions, long
descriptions, markdown and
whatnot is all up to you and is a personal preference. It is not
enforced by the PHPDoc Standard.

I you want to link to a piece of external documentation, just use the
following snippet:

/** @link http://example.com/docs/mything.php */

Perhaps that suits your style?

I personally prefer concise DocBlocks that contains implementation information
regarding that specific source element; something which I consider to be hard
to capture in external documentation without having to wade through hundreds
of page of information that only has meaning in its context.

Also:

> By my opinion, changes to or replacement to PHPDoc should not be made nor
> implemented by a single vendor, what phpDocumentator is.

phpDocumentor has always spear-headed the PHPDoc de-facto standard; and why
shouldn't we continue that tradition? Even by formalizing it? Every
bit of input is
appreciated and used to make sure inline documentation is accessible
to everyone.
I personally do not believe it is made by phpDocumentor, it is a
community effort.

On Sun, Sep 30, 2012 at 8:22 PM, Matīss Roberts Treinis

[Andrew Eddie]

On Monday, 1 October 2012 00:11:42 UTC+10, Mike van Riel wrote:

You can find the working draft in our repository:
https://github.com/phpDocumentor/phpDocumentor2/blob/develop/docs/PSR.md

Mike I think this is an awesome start to defining the standard.  It would be great to get the PHPDoc standard officially recognised.

On Monday, 1 October 2012 04:22:33 UTC+10, Matīss Roberts Treinis wrote:

Greetings. 

By my opinion, changes to or replacement to PHPDoc should not be made nor implemented by a single vendor, what phpDocumentator is.

Crude example is already section 5.2 of particular PHPDocumentator PSR - it already suggests Markdown in long description, which will create "bloat" as it is currently with code documented in a way using HTML tags in a long description. Same with a code examples. 

I sort of agree, but for different reasons (but also see Mike's follow-up to your points).  I don't think the specification should make any core recommendation of any decoration system (HTML, Markdown, etc); it should just define the raw PHPDoc standard.  That said, decoration is a logical extension of the standard and there is room for advising which way custom parsers (phpDocumentor, Doxygen, et al) support such decoration and that's probably a good fit for an appendix.

Regards,

Andrew Eddie

[David Négrier]

Hi Mike,

I think this is an awesome start too.

I have just one small comment.

I don't know if this is the right place to comment on this (or if you are ready for comments), but I'll start here.

My main comment will be about the way you describe arrays in the @type annotation.

Basically, you specify that we can use stuff like this:

@type int[]

or

@type MyOject[]

This is fairly cool, but I think that by reading the documentation, you cannot make the difference between indexed arrays and associative arrays (which are the same "array" object in PHP but have a completely different meaning)

My thought is that by reading documentation, we should know whether the developer expects us to provide a plain array, or a hashtable.

I'm pretty interested in this aspect, because I'm the lead developer of Mouf (http://mouf-php.com), a PHP visual dependency injection framework.

In Mouf, I'm analysing the @var annotation by reflection, and generating a user interface from the @var.

And basically, I'm not generating the same UI depending on whether it is an associative array or an indexed array.

Right now, I'm using:

@var array<MyObject> for a simple array

@var array<string, MyObject> for an associative array

Here is a screenshot of the rendering in Mouf: http://www.diigo.com/item/image/37ggx/vap2

I understand you might not like this notation, but would it be possible to find one that capture the idea of indexed VS associative array?

Maybe:

@type MyObject[int]

vs

@type MyObject[string]

?

I'm really open to any suggestion.

David.

[Andrew (@phpAndy)]

Is it appropriate to also consider the same idea for multidimensional arrays (e.g.  @type: object[int][string])?

Just a thought,

AP

[Johannes Schmitt]

I'd also like to add one more case where the current type system could be enhanced, and that is option arrays; meaning basically maps with specific key/value pairs. Especially for those, it would be important to know which keys are allowed, and what their expected type is.

Let's say you have an option array with the keys "required", and "label", here are some alternatives that I could imagine:

@type array("required" => boolean, "label" => string)  // a bit long
@type ["required" => boolean, "label" => string] // a bit shorter using PHP 5.4 style
@type {"required": boolean, "label": string} // again a bit shorter using JSON-syntax

Maybe there are even more ways to express this.

As for multidimensional arrays, they could be written as: array<array<string>>

Cheers,
Johannes

--

You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To post to this group, send email to php...@googlegroups.com.
To unsubscribe from this group, send email to php-fig+u...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msg/php-fig/-/M1oe0Tu5oZcJ.

[Mike van Riel]

Associative arrays and array format declarations (a.k.a. option
arrays) are a bit of a troublesome topic; I
think this is the best place to discuss such an issue (although a new
topic might be suitable instead of
hijacking this one ;))

The current array notation, type[], exists because it is used in at
least Java to document that this is an
array with elements of a specific type, as such I would be reluctant
to adopt the <> notation as I know
that [] is in use with IDE vendors.

For multi-dimensional arrays I generally prefer to use the `type[][]`
notation indicating that you have an
array containing arrays containing elements with the given type. Since
this is a homebrew notation it
is very much open for debate.

Regarding option arrays and enumerations (which do not differ much
except that the key is not offered
a Type as value but a constant value) I think it would make the
@type/@var tag hard to read if you try
define a complete option array / enumeration inside the tag itself.

As such I would be tempted to adopt a strategy that is in use with the
WSDL language by defining a
substitution type (struct-like thing?) in the same DocBlock that
defines the option array or enumeration
and still allows the @var/@type to have a singular 'Type'.
(This is brainstormed just now, so please offer your thoughts!)

An example _might_ be:

/**
* Short description.
*
* @type :myEnum $variable1
* @type :myOptionArray $variable2
*
* @define myEnum ['optionA','optionB']
* @define myOptionArray ['required' => boolean, 'label' => string]
*/

With regards to the option array declaration notation I would opt to
use the PHP
5.4 notation as that is (going to be) recognizable and will become
intuitive for
developers.

Your thoughts?

[Johannes Schmitt]

Allowing to define custom doc types sounds like a good enhancement to me, some questions:
- What would the scope of these custom doc types be (global/all files, file only, class only, method only)?
- Kind of related to the first question, where could these types be defined (on which code elements)?

However, if you just use the option array in a single place, then I'd say it should also be possible to use an inline definition and we should not strictly require to define a separate type (directly use @type without @define).

Regarding collections, in Doctrine we currently support "array<T>" to describe a list of types; we chose this mainly because Java is already using it, for example "List<Foo> myList = new HashList<Foo>();". It could be that "[]" was used in doc comments in Java at some point when it had no generics support, but I have not seen this anytime recently. However, I'm open to solely use the "[]" style, it's a bit more succinct, but it also should make a parser a bit more complex to implement.

Here some examples comparing the two styles:

Lists (keys are not insignificant, and of integer type)
"array<Foo>", or "Foo[]"

Maps (keys are significant, and of integer and/or string type)
"array<string|integer, Foo>", or "Foo[string|integer]"
"array<string, Foo>", or "Foo[string]"

Multidimensional Lists:
"array<array<string>>", or "string[][]"

Multidimensional Maps:
"array<string, array<string, Foo>>", or "Foo[string][string]"

Mixed multidimensional collections:
"array<array<string, Foo>>", or "Foo[][string]"

After writing these, I'm not sure whether the [] works that well, especially if you're dealing with multidimensional arrays. Regardless of which annotation we choose eventually, I'd opt to be consistent though and either use "[]" or "array<>", and not mix them.

Cheers,
Johannes

[Mike van Riel]

Hi Johannes,

I am going to give some inline answers to assist with context,

On Mon, Oct 1, 2012 at 8:56 PM, Johannes Schmitt <schmi...@gmail.com> wrote:
> Allowing to define custom doc types sounds like a good enhancement to me,
> some questions:
> - What would the scope of these custom doc types be (global/all files, file
> only, class only, method only)?

Good question, I'd be adverse to having global Custom Doc Types as
that can easily lead to confusion.
Not in the least place where to find the definition. Also, if you need
a Custom Doc Type in more than one
class I'd _seriously_ consider making it a real (struct) class.

Concerning scope I am in doubt, the advantage of local scope is that
it is clear while reading a DocBlock
what is defined and it seems unnecessary to share scope between
members of a class. On the other hand
I can imagine that a getter and setter share the same Custom Doc Type
and it seems odd to duplicate the
definition.

As such I would propose that the definition can be in both local as
well as class scope, but that the usage in
a @var/@type tag should make it clear which location it is. (for
example, a single colon implies local scope
and a double colon class scope?).

> - Kind of related to the first question, where could these types be defined
> (on which code elements)?

My answer to this would be that in any location where you would be
able to use a `Type` as defined in the
PHPDoc PSR you would be able to use this.

> However, if you just use the option array in a single place, then I'd say it
> should also be possible to use an inline definition and we should not
> strictly require to define a separate type (directly use @type without
> @define).

I think allowing that would add to the flexibility of this proposal; however I
would personally recommend having a separate definition. But that is
personal :)

> Regarding collections, in Doctrine we currently support "array<T>" to
> describe a list of types; we chose this mainly because Java is already using
> it, for example "List<Foo> myList = new HashList<Foo>();". It could be that
> "[]" was used in doc comments in Java at some point when it had no generics
> support, but I have not seen this anytime recently. However, I'm open to
> solely use the "[]" style, it's a bit more succinct, but it also should make
> a parser a bit more complex to implement.

I have found a reference to the use of Generics in @param tags here:
http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#@param

But if I am reading this correctly then Java has a simplified notation
as they omit the
'array' or 'Class' keyword. Since I do not know how Generics exactly
work I find this
hard to wrap my head around.
This does however lead me to the thought that I might not be the only
one and I think
that the [] notation might be more intuitive for PHP Developers since
they are used
to that being an array symbol?

>
> Here some examples comparing the two styles:
>
> Lists (keys are not insignificant, and of integer type)
> "array<Foo>", or "Foo[]"
>
> Maps (keys are significant, and of integer and/or string type)
> "array<string|integer, Foo>", or "Foo[string|integer]"
> "array<string, Foo>", or "Foo[string]"
>
> Multidimensional Lists:
> "array<array<string>>", or "string[][]"
>
> Multidimensional Maps:
> "array<string, array<string, Foo>>", or "Foo[string][string]"
>
> Mixed multidimensional collections:
> "array<array<string, Foo>>", or "Foo[][string]"
>
> After writing these, I'm not sure whether the [] works that well, especially
> if you're dealing with multidimensional arrays. Regardless of which
> annotation we choose eventually, I'd opt to be consistent though and either
> use "[]" or "array<>", and not mix them.

I agree, I am very interested to other's opinion on which they believe
to be preferable.

Do we know if there are IDEs that support the Generic-style notation?

[Ryan Parman]

The two areas of the PHPDoc de-facto standard that I have the most trouble with are (a) lists and hashes, and (b) option hashes.

I think that being explicit that a parameter accepts an array of "somethings" is important, so I'd be inclined to use the `array<...>` syntax. I've also seen this format used in both Java and Ruby source.

The tougher issue to solve is option hashes. At present, if you have this:

$variable = new MyClass(array(

    'key1' => 'value1',

    'key2' => 'value2',

    'key3' => 'value3',

));

There isn't currently a good way to document the names of the keys and a description of the values.

I'm just exploring here, but what about something like this:

@param [type] $param1 [description]

@param [type] $param2 [description]

    @option [type] $param2 "key1" [description]

    @option [type] $param2 "key2" [description]

@param [type] $param3 [description]

Thoughts?

[Kirill Chebunin]

First of all the huge +1 to move PHPDoc to PSR.

What about array notations i think generic style gives more features as it is not about arrays but about templates.
ex. we can mark our class as @template <T> and use this in method and properties docblocks (@return T, @param T, etc).

2012/10/2 Ryan Parman <ry...@ryanparman.com>

--

You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To post to this group, send email to php...@googlegroups.com.
To unsubscribe from this group, send email to php-fig+u...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

--
Best Regards,
Kirill chEbba Chebunin,
Programmer to the bone,
Moscow, Russia.

[Mike van Riel]

On Tue, Oct 2, 2012 at 4:13 AM, Ryan Parman <ry...@ryanparman.com> wrote:
> The two areas of the PHPDoc de-facto standard that I have the most trouble
> with are (a) lists and hashes, and (b) option hashes.

I can well imagine that since the original de-facto standard doesn't cover it.

> I think that being explicit that a parameter accepts an array of
> "somethings" is important, so I'd be inclined to use the `array<...>`
> syntax. I've also seen this format used in both Java and Ruby source.
>
> The tougher issue to solve is option hashes. At present, if you have this:
>
> $variable = new MyClass(array(
> 'key1' => 'value1',
> 'key2' => 'value2',
> 'key3' => 'value3',
> ));
>
> There isn't currently a good way to document the names of the keys and a
> description of the values.
>
> I'm just exploring here, but what about something like this:
>
> @param [type] $param1 [description]
> @param [type] $param2 [description]
> @option [type] $param2 "key1" [description]
> @option [type] $param2 "key2" [description]
> @param [type] $param3 [description]
>
> Thoughts?

I am personally not very fond of this notation as it seems rather
verbose and looking
at it doesn't immediately clear what's going on.

Have you read the suggestions in earlier mails by Johannes and me?

[Mike van Riel]

This can be accomplished now using a namespace alias, which is a valid
language construct and thus recognized by PHP.

`use MyClass as T;`

PHP does not have a concept of Generics and not of the <Class> operator.
That makes me hesitant to adopt such a notation as it would mean that
users would have to learn a new sub-notation.

Can you think of other use-cases where it would help? Perhaps that would
change the situation?

[Ryan Parman]

On Oct 1, 2012, at 11:09 AM, Johannes Schmitt <schmi...@gmail.com> wrote:

> @type array("required" => boolean, "label" => string) // a bit long
> @type ["required" => boolean, "label" => string] // a bit shorter using PHP 5.4 style
> @type {"required": boolean, "label": string} // again a bit shorter using JSON-syntax

On Oct 1, 2012, at 11:28 AM, Mike van Riel <draco...@gmail.com> wrote:

> /**
> * Short description.
> *
> * @type :myEnum $variable1
> * @type :myOptionArray $variable2
> *
> * @define myEnum ['optionA','optionB']
> * @define myOptionArray ['required' => boolean, 'label' => string]
> */

The biggest problems with these notations is that they don't allow for *documenting* the option. In complex pieces of software with many optional parameters, there needs to be a sane way to document the keys.

To fill the gap, I've been treating @params as multiline while using markup (e.g., HTML, Markdown, ReStructuredText) to notate lists (<li>). This isn't ideal, but it works in a pinch (if you don't rely on IDE support).

Ideally, whatever solution we can cook up for this could also be applied to the @method tag for documentation purposes.

[Mike van Riel]

On Tue, Oct 2, 2012 at 8:35 AM, Ryan Parman <ry...@ryanparman.com> wrote:
> On Oct 1, 2012, at 11:09 AM, Johannes Schmitt <schmi...@gmail.com> wrote:
>
>> @type array("required" => boolean, "label" => string) // a bit long
>> @type ["required" => boolean, "label" => string] // a bit shorter using PHP 5.4 style
>> @type {"required": boolean, "label": string} // again a bit shorter using JSON-syntax
>
> On Oct 1, 2012, at 11:28 AM, Mike van Riel <draco...@gmail.com> wrote:
>
>> /**
>> * Short description.
>> *
>> * @type :myEnum $variable1
>> * @type :myOptionArray $variable2
>> *
>> * @define myEnum ['optionA','optionB']
>> * @define myOptionArray ['required' => boolean, 'label' => string]
>> */
>
> The biggest problems with these notations is that they don't allow for *documenting* the option. In complex pieces of software with many optional parameters, there needs to be a sane way to document the keys.

That is a good point that you are making there.
The biggest challenge I see is that we are trying to create a virtual
language construct where there is none. An option array could
very well be modelled as an option class, which can be documented
without a problem.

So the point may be that an @define tag is too limited in scope as you
need to describe multiple properties of one struct. (the option array
can have properties and each key has at least one property).

@type was specifically constructed to be able to serve in any
situation where you have a variable with a key, so it another options
is that it can represent the individual key of your option array. But
how do you sanely represent the array itself in a DocBlock without
convoluting the code?

example suggestion:

/* @struct myOptionArray(key1, key2) {
/* @type boolean key1 [description]
/* @type integer key2 [description]
/* }

And to aid people want to keep a verbose document without descriptions
the following alternative format could work?

/* @struct myOptionArray(boolean key1, integer key2)

This is just a quick brainfart, don't pin me to it ;) Especially since
it can have a severe impact on the standard by introducing a sub-scope
wit braces

[Johannes Schmitt]

I really like the idea of the @template annotation (I'm not sure about the name as template could be misunderstood), but this could be useful for any kind of collection, and improve IDE support for the foreach variable. Let's take a look at an example:

/**
 * @template <T> The type of the individual elements
 */
class ArrayCollection implements IteratorAggregate
{
    private $elements;

    /**
     * @param array<T> $elements
     */
    public function __construct(array $elements)
    {
        $this->elements = $elements;
    }
 
    /**
     * @return Iterator<T>
     */
    public function getIterator()
    {
         return new ArrayIterator($this->elements);
    }
}

// usage
/** @type ArrayCollection<Foo> */
$col = new ArrayCollection();
foreach ($col as $elem) {
    // $elem is instance of Foo here
}

For some people, this might be a bit overboard, but fortunately the "@template" annotation would solely be necessary on the generic class, and does not need to be used by end-users anymore. They would just not benefit from better IDE support in that case. We could also allow to specify a common super type for example using "@template <T extends object>" meaning that whatever T is it must at least be an object. So, if "@type ArrayCollection" was used without the "<...>", T would implicitly be assumed to be an object. That way, people who want to take advantage of the better IDE support can, and others don't have to bother. It also allows for a smooth upgrade path.

Regarding documenting option keys, maybe the documentation itself better fits into the long description? IMO there is some merrit in keeping the @param part short, so that you can get the allowed keys in a quick glance, and if you need more info because they are not self-explanatory and you don't know what they are doing yet, then you can take a look at the long description. Another option might be to split the type definition and the description into two separate annotations which would keep the definition of what is available short, and also serve the need for a more structured documentation.

[Kirill Chebunin]

Another example.

/**
 * @template <T>
 */
interface Repository
{
    /**
     * @return array<T>
     */
    public function findAll();

    /**
     * @return T|null
     */
    public function find($id);
}

class RepositoryFactory
{
    /**
     * @return Repository<User>
     */
    public function getUserRepository() {/**/}
}

// or

/**
 * @template <T> <User> (syntax is just for example)
 */
class UserRepository implements Repository
{
    /* ... */
}

Syntax and tag name needs a discussion. "@template" was just the first that i found in my mind =)

2012/10/2 Johannes Schmitt <schmi...@gmail.com>

[Ryan Parman]

On Oct 2, 2012, at 12:51 AM, Johannes Schmitt <schmi...@gmail.com> wrote:

Regarding documenting option keys, maybe the documentation itself better fits into the long description? IMO there is some merrit in keeping the @param part short, so that you can get the allowed keys in a quick glance, and if you need more info because they are not self-explanatory and you don't know what they are doing yet, then you can take a look at the long description.

As the long-term developer of the AWS SDK, I have first-hand experience to the contrary.

First of all, parameters will change over time as the web service APIs evolve. Learning the options key once doesn't mean they'll stay that way forever (for better or worse…). As such, treating the option-key descriptions as second-class documentation citizens only serves to make the software more difficult to understand over time.

Another option might be to split the type definition and the description into two separate annotations which would keep the definition of what is available short, and also serve the need for a more structured documentation.

This was the first thing that we tried. Feedback from our customers (when we generated the HTML docs from this type of notation) was that the jumping around from one block to another while trying to understand what options were available made things more difficult to understand.

We solved the UI problem by embedding HTML lists (ul, li) into the docblocks themselves, but this makes the source docblocks far more difficult to read, write and understand.

Ruby's YARD project does a good job of this with their @option [1] and @!method [2] tags. Since Ruby is generally brace-less, the documentation follows that pattern by supporting indented tags/descriptions. Mike suggested using braces, IMO but that's not a terrible idea.

The current @param syntax is as follows:

    @param [type] [variable] [description]

In cases where the type is an associative array, what if we enabled something like this for option-keys?

    @param [type] [variable] [description] {

        @option [type] [key] [description]

    }

It simplifies the syntax I suggested earlier by leveraging some of the better ideas from Mike. I wouldn't be opposed to using indenting either, but I'm not yet sure of the impact of making whitespace important.

Using this same pattern, we could apply it to @method [3].

    @method [return type] [name]([type] [parameter], [...]) [<description>]

...or...

    @method [return type] [name]([type] [parameter], [...]) {

        [<description>]

        @param [type] [variable] [description] {

            @option [type] [key] [description]

        }

    }

In this case, @method follows the same pattern as a standard docblock — only encapsulated within braces as a sub-construct. Since the pattern is generally the same, implementing it would be just as easy to understand.

--

[1] http://rubydoc.info/docs/yard/file/docs/Tags.md#option

[2] http://rubydoc.info/docs/yard/file/docs/Tags.md#method

[3] http://phpdoc.org/docs/latest/for-users/tags/method.html

[Mike van Riel]

I agree with Ryan that giving meaning to the values of option arrays
would benefit the
generation of documentation. It is of course still an option to use
the description for
that, that is up to the developer to decide on whether to use this option.

As such I have created a gist that demonstrates the options that have
been suggested
thus far for option arrays at: https://gist.github.com/3822861

Please note I have not included anything related to the array<T>
format because I believe
that it would help to separate that into a different gist/discussion.

My own conclusion based on the gist is that:

1. The end result of my own suggestion and that of Ryan only differ in
which tag is adopted.
I prefer @type because an entry in an option array is comparible
to a property, which also uses
@type + it does not introduce a new tag. (more tags = more for
people to remember = feature bloat IMO)
2. I have added the last suggestion later after reviewing the results
of the first gist. I think it would be better
to separate the structure of the into a semi-type 'struct' because
that is what you are effectively doing; an
option array is a form of informal class definition with only
properties (aka struct in other languages).

[Mike van Riel]

To illustrate this concept and show how it could be approached in the
'conventional' method I have
created a gist: https://gist.github.com/3823010

To be honest, I am still very much in doubt. I can see where this is
going but I am wondering if it
is not too complex and demands a learning curve to use? This would
also require a shift for existing
IDEs to adopt this as the syntax is not supported by them (at least
not by phpStorm, with which I
just tested).

I see Ruby uses it as well.. can you please try to provide more
information; which benefits does
adopting Generic notation offer? Which downsides do you see? Which
downsides do you see with
the current notation?

Don't get me wrong: I am seriously trying to understand here.

[Ryan Parman]

Mike,

I've made some slight adjustments to the options you posted.

https://gist.github.com/3822861#gistcomment-582172
https://gist.github.com/3822861#gistcomment-582174

My goal is to piggy-back on the PHPDoc patterns that people already know, while addressing a couple of gaps in the PHPDoc de-facto standard (i.e., documenting option-hashes, and providing documentation for dynamically-accessed methods/properties using @method/@property).

I don't feel strongly about whether @type or @option is selected, although my preference is for @option. Also, after taking a look at the examples you posted in the gist, I've decided that I'm pro-brace.

[Mike van Riel]

Those are quite interesting variations! Please see my remark on the
gist for more information.
(message also posted for readers on this group, who do not receive a
notification of my remark in the gist)

[Ryan Parman]

> @skyzyx Those are interesting variations! So, if I summarize this in words:
>
> A tag may replace its multiline description with a set of curly braces; any content inside those curly braces are interpreted as an inline DocBlock for that specific element.

Precisely. I don't know how valuable it would be for tags such as @copyright, @api, @deprecated, etc., but for tags such as @param, @method and @property, this could be a very powerful new construct that would enable clearer documentation for end-users.

[Mike van Riel]

Some more discussion went on In https://gist.github.com/3822861 and I
think now is a good time to say yes or nay.

Can people on the list add more comments or considerations to this?
Otherwise I or Chuck will add this to the PSR

[Matīss Roberts Treinis]

Pardon me, if I am mistaken, but PSR proposal in phpDocumentator has been out for 5 months, and looking through history I see only two contributors. Am I missing some mailing list discussion behind this? 

This topic is week old, and has only a dozen or so contributions (more attraction maye). I fail to see any serious discussions going on here about the topic either.  

Mike, could You compile a overall PSR proposal and start a new discussion about it? 

I think we should put out that compilation for discussion here to urge community for wider discussion about the topic, for example, for limited amount of time - a month maybe? And then we should make our communities aware of this, to draw more discussion. 

I might be missing something, but it seems we here are a relatively small group of professionals having a discussions about serious enough things which would need a wider attention from PHP community, within or outside PHP-FIG working group and contributors. 

[Mike van Riel]

As I addressed in an earlier message, the PSR is a working draft and
is not (yet) submitted to
this group as it is not finished yet. The number of contributors to
that document exceeds 2 but
those are non-code contributors.

The intention behind this working draft was to create a complete
document so that there is
content to discuss and then champion it to this group and invite
everyone in the community
to comment and discuss it.

So no, I am not going to post a PSR proposal yet because too many
topics are still unfilled.
This thread now only addresses an absent feature of PHPDoc. Once the
PSR proposal
document is fully written then I will champion it.

> To view this discussion on the web visit

> https://groups.google.com/d/msg/php-fig/-/SFt36WognY4J.

[Ryan Parman]

+1 to the ideas discussed and refined in https://gist.github.com/3822861

[Tim Otten]

I like the example mike_van_riel2():

/**
* ...
*
* @param `Options` $options [description]
*
* @struct Options {
* @type string NAME [description]
* @type string "label" [description]
* @type integer "type_id" [description]
* @type boolean "visible" [description]
* @type string "default" [description]
* }
*
* @return void
*/
function mike_van_riel2($options = array())

This notation can be intuitively adapted to answer questions like:

* How does one use the same array data-structure in multiple methods?
* How does one describe an array data-structure for a return?
* How does one describe a class property which stores an array data-structure?
* How does one described nested array data-structures?

A particuarly notable part of the example is the extra control character in the @param type (`Options` vs Options); this seems like a good cue that the type is not a formal PHP type -- that the type is defined by some other means. There are other use-cases for this. For example:

* In Drupal, the Form API and Schema API are predictable data-structures, but they are not quite static structs, and it would be useful for an IDE to autocomplete keys, to generate warnings for unknown keys, or to apply type-checking.

* In the application/framework I work on, there are many arrays with dynamic data-dictionaries -- data-dictionaries that aren't written in any one spot but which can be discovered using an API call. If a documentation-generator or IDE knew to make that API call, then it could provide autocompletion, type-checking, etc.

So here's a proposal for modifying <type> expressions to allow non-native type names:

== BNF for <type> expressions ==

<type> ::= "mixed" | <primitive-type> | <class-type> | <external-type>
<primitive-type> ::= "string" | "double" | ...
<class-type> ::= "A-Za-z" {"A-Za-z0-9_\"}+
<external-type> ::= <external-type-provider> ":" <external-type-name>
<external-type-provider> ::= "A-Za-z" {"A-Za-z0-9_\"}+
<external-type-name> ::= "A-Za-z" {"A-Za-z0-9_\"}+

== EXAMPLE: Declare struct types in docblocks ==

/**
* An HTTP client
*
* @struct HttpOptions {
* @type int timeout
* @type string user_agent
* @type string referer
* @type `struct:HttpAuthentication` auth
* }
* @struct HttpAuthentication {
* @type string username
* @type string password
* @type string certificatePath
* }
*/
class HttpClient {

/**
* @var struct:HttpOptions
*/
protected $defaultOptions;

/**
* Send an HTTP GET
*
* @param string $url
* @param struct:HttpOptions $options
* @return string
*/
function get($url, $options = array())

/**
* Send an HTTP POST
*
* @param string $url
* @param string $data
* @param struct:HttpOptions $options
* @return string
*/
function post($url, $data, $options = array())
}

== EXAMPLE: Drupal Form API ==

/**
* Implement hook_form_alter
*
* @param Drupal:FormElement $form
* @param Drupal:FormState $form_state
* @param string $form_id
*/
function mymodule_form_alter(&$form, &$form_state, $form_id)

== EXAMPLE: Business Logic with CiviCRM API ==

/**
* Record a soft-credit for someone that facilitated a contribution
*
* @param CiviAPI:Contact $contributor the person who facilitated the contribution
* @param CiviAPI:Contribution $hardCredit the original contribution
* @return CiviAPI:Contribution the soft credit for the facilitator
*/
function createSoftCredit($contributor, $hardCredit)

[Ryan Parman]

So, one more thing that just occurred to me: Nested hashes.

Some of us need to support nested hashes of options for one reason or another. How well would this scale for that case? Would the "inner" sections be able to recurse (potentially) infinitely (or until PHP blows a fuse)?

[Ryan Parman]

Also, Mike van Riel, do you presently have a plan for updating https://github.com/phpDocumentor/ReflectionDocBlock with these syntax changes?

[Mike van Riel]

The new ABNF notation support recursing of 'Inline PHPDoc' elements.
This was the most simple and flexible variation.
Whether a project allows it or wants it is beyond the scope of this
specification as far as I am concerned; the tools are there, it is up
to the author to properly use it ;)

Regarding the ReflectionDocBlock component; once the PSR is approved I
will certainly update it. To do so now might be too soon, I'd like
some community feedback first.
I have a lot of things to do and too little time (who doesn't) and
that means to me that I will spend time on where the demand is (which
is prepping phpDocumentor2 for its first beta and eventual release).

[Ryan Parman]

Is anybody working on a way to parse the contents of braces (e.g., {...}) yet?

Whether or not we use @param, @option, @struct, or anything else, they all seem to depend on the ability to parse the contents of braces as sub-blocks.

I just wanted to know before I start the work of patching https://github.com/phpDocumentor/ReflectionDocBlock myself. If you are, let me know so I can fork from you and we can work together on it.

[Mike van Riel]

Not currently; I am working on the ReflectionDocBlock but that is to improve
the way Types are expanded for a bugfix wrt @param

> --
> You received this message because you are subscribed to the Google Groups
> "PHP Framework Interoperability Group" group.
> To post to this group, send email to php...@googlegroups.com.
> To unsubscribe from this group, send email to
> php-fig+u...@googlegroups.com.

> To view this discussion on the web visit

> https://groups.google.com/d/msg/php-fig/-/GZ_uQQXbd90J.

[Chris Dieringer]

For those visiting this thread well after the conversation has tapered off, it appears that the 'standards' link is now: http://phpdoc.org/docs/latest/index.html