[PSR-5] enhancements

[jaapio]

This pull request introduces enhancements to the PHPDoc specification (proposed/phpdoc.md) by refining tag handling and adding support for inline tags. The most important changes include updates to the ABNF definition for tags, the introduction of inline tags, and the addition of tag specialization for improved metadata organization.

Enhancements to tag handling:

• Updated the ABNF definition to modify the syntax for tag-specialization and tag:

  • tag-specialization now excludes the - character, and tag syntax includes an optional specialization prefix followed by a hyphen.

• Added the concept of tag specialization (5.3.1 Tag Specialization) to provide a scoped context for tags. Specialized tags can differ from the standard catalog, and parsers may ignore unsupported specialized tags.

Support for inline tags:

• Introduced inline tags (5.2.1 Inline tags) within descriptions. Inline tags must start with {@ and end with }. Escaping is supported for closing braces using {}. Inline tags are limited to regular tags and do not apply to annotation tags.

Structural refinements:

• Updated the table of contents to reflect the addition of inline tags and the reorganization of tag-related sections.

Minor Adjustments:

Updated recommendations for formatting in summaries and descriptions, such as discouraging formatting in summaries and clarifying Markdown usage in descriptions.

[kenguest]

Looks great

[Crell]

"A single line or two" is very squishy language. Should we just require a single line? PER-CS gives you up to 120 characters...

[jaapio]

This is again based on the existing implementations of the tools reading docblocks. I took phpDocumentor as a standard here, since all tools are following. I'm not trying to set a new standard here, as the docblocks are already like this for many years.

But I get your point. We need to sharpen the definition here.

The full definition of a summary is complex. :-(

https://github.com/phpDocumentor/ReflectionDocBlock/blob/5.x/src/DocBlockFactory.php#L226C1-L238C14

      # 2. Extract the summary
      (?:
        (?! @\pL ) # The summary may not start with an @
        (
          [^\n.]+
          (?:
            (?! \. \n | \n{2} )     # End summary upon a dot followed by newline or two newlines
            [\n.]* (?! [ \t]* @\pL ) # End summary when an @ is found as first character on a new line
            [^\n.]+                 # Include anything else
          )*
          \.?
        )?
      )

[jaapio]

I updated the wording a bit. To make it more explicit.

A Summary MUST be a concise abstract of the Structural Element’s purpose. It is RECOMMENDED to keep the Summary to a single line, though two lines MAY be used if needed.

[Crell]

Does this implicitly mean supporting HTML, too?

[Crell]

Also... which Markdown? :-) There are many flavors.

[jaapio]

Maybe we just have to pick CommonMark as that's the most common standard I know in markdown. The set is limited, but as far as I know, most tools support the syntax of CommonMark.

I need to do some more research on how other php based tools are doing this, but mostly it's just phpDocumentor doing this. I didn't find any other libraries that handle the description of docblocks in the wild. Apart from the IDE's. We would need some people from those sides to have a look at this.

[samdark]

https://github.com/yiisoft/yii2-apidoc, https://www.yiiframework.com/doc/api/2.0 are generated using it.

[jaapio]

I updated the document with some small improvements regarding "summary" and an extra section about the usage of Markdown in descriptions.

Please let me know what you think.