Inline php-doc definition

[Rasmus Schultz]

I'm confused by the opening paragraph in the section on "[inline](https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#54-inline-phpdoc" php-doc:

Specific Tags MAY have an "Inline PHPDoc" section at the end of the "Tag" definition.

There seems to be some confusion as to what "inline" means - the term appears to be overloaded to describe two very different things:

1. "inline", as per the example in the opening section on "inline php-doc", where a description and additional tags can be nested child tags inside a parent tag.
2. "inline", as per the "inline" variation of @example or @see, which are tags appearing inlined inside a description body.

I think the term "inline" best fits the second category of tags, which don't have a parent tag.

I also think the term "nested" might fit the first category of tags much better, since these are really child elements of a parent tag and aren't "embedded" in a description.

It's also worth nothing (in the spec) that a tag can in fact both be "inline" and "nested" - for example, an inline @see tag can be embedded in a description body of a @method tag nested inside a @typedef tag.

An "Inline PHPDoc" is a "PHPDoc" element enclosed in braces and is only present at the end of a "Tag" sequence, unless specified otherwise in a "Tag" definition.

Maybe this ambiguous primarily because of the ambiguity described above, but it could sound like you're saying that all tags can be used inline in descriptions unless specified otherwise, which I don't think is true? What it should say, probably, is that tags aren't automatically supported for inline use in descriptions, unless the tag definition explicitly defines it for inline use?

The "Inline PHPDoc" element MUST replace any description that COULD have been provided.

I don't even know what that means :-)

On a related note, we support markdown, which would be a much more intuitive (and compatible!) thing to use in descriptions than inline php-doc tags. I'm not entirely sure where I'm going with that, but... inline links, e.g. @see and @link in php-doc, are generally written as [text](link) in markdown, so... we have some overlap there - although I do realize the spec currently allows descriptions to be interpreted as markdown, already many tools are doing it, and we might as well adopt it full-on if we're going to allow it, why not? Perhaps if markdown could take over the role than "inline" tags fulfill right now, we wouldn't need both "inline" and "embedded" tags in the spec?

[Richard Fussenegger]

I also think that the usage of inline is ambiguous and I like your idea of using the word nested for the (well) nested PHPDoc.

The "Inline PHPDoc" element MUST replace any description that COULD have been provided.

This is regarding a situation like the following (I think or at least I understand it like that):

/**
 * @tag This is a description, but this tag allows nested PHPDoc {
 *     This is the nested summary.
 *     @tag foo
 * }
 */

Tools have to drop the This is a description, but this tag allows nested PHPDoc part in favor of the nested PHPDoc.

I mentioned the Markdown and inline tag overlap in the other issue of yours as well. I would also strongly recommend dropping inline tags in favor of full Markdown support (for summaries, descriptions, heck pretty much everywhere).

[Mike van Riel]

I mentioned the Markdown and inline tag overlap in the other issue of yours as well. I would also strongly recommend dropping inline tags in favor of full Markdown support (for summaries, descriptions, heck pretty much everywhere).

Not an option; inline tags have a long history and I am against breaking BC in such a way. Also: inline tags do stuff that markdown doesn't support.

[Richard Fussenegger]

Not the @link tag (that was the context were I mentioned the overlap), but the @see does and its inline version makes total sense.

You already deprecated @link btw.

[Chuck Burgess]

I'm not keen on replacing the link/see mechanism with raw Markdown, not at all.

Concerning the proposed deprecation of @link, that was Mike and I thinking that it was redundant with @see, and thus choosing one to do the jobs of both tags. Original use of @see was only for pointing to structural elements, nothing else.

If the crux of this request is renaming "inline PHPDoc" to "nested PHPDoc", I can probably live with that, thus leaving "inline" only to its historical context of inline tags.

Ping @ondrejmirtes @muglug @neuro159 @mindplay-dk @GaryJones @mvriel @jaapio for opinions.

[Chuck Burgess]

@mindplay-dk , please bring this up as a new thread on the FIG mailing list for discussion -- https://groups.google.com/forum/#!forum/php-fig