Closed mindplay-dk closed 5 years ago
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).
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.
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.
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.
@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
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:
There seems to be some confusion as to what "inline" means - the term appears to be overloaded to describe two very different things:
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.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?
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?