Skip to content

SI-5795 empty scaladoc tags should be omitted from output#4427

Merged
lrytz merged 3 commits intoscala:2.11.xfrom
gourlaysama:wip/t5795-scaladoc-empty-params
Apr 9, 2015
Merged

SI-5795 empty scaladoc tags should be omitted from output#4427
lrytz merged 3 commits intoscala:2.11.xfrom
gourlaysama:wip/t5795-scaladoc-empty-params

Conversation

@gourlaysama
Copy link
Contributor

Empty scaladoc tags, like @param, @return, @version, etc. should
be omitted from the output when they have no meaning by themselves.

They are still parsed, for validation (warning that a tag doesn't
exist and so on), but are removed, if empty, when building the Comment.

The only one that stays even when empty is @deprecated, so that the
class name can be striked-through. "Deprecated" also appears in the
header, even if there is no message with it.


The first two commits fix two other tag-related bugs in scaladoc, found while fixing this one. See individual commit messages.

Empty scaladoc tags used to completely break the HTML layout of
classes and methods.

See the difference between before [1] and after [2].

[1]: http://static.gourlaysama.net/img/scaladoc_t5795_before.png
[2]: http://static.gourlaysama.net/img/scaladoc_t5795_after.png
@scala-jenkins scala-jenkins added this to the 2.11.7 milestone Apr 2, 2015
Consider the following code:

/**
  * @see
  * @deprecated
  */
  object Foo

The comment parser properly parsed the body of the 'see' tag as
empty, but not the one of 'deprecated': it supposedly contains a single
character, a newline '\n', which is wrong.

This always happened to the last tag in the list; it is always appended
a new line (whether empty or not), which breaks formatting (and things
later on that test if a body is empty of not).
@gourlaysama gourlaysama force-pushed the wip/t5795-scaladoc-empty-params branch from 3f9adbc to 3183c2b Compare April 2, 2015 17:14
Empty scaladoc tags, like `@param`, `@return`, `@version`, etc. should
be omitted from the output when they have no meaning by themselves.

They are still parsed, for validation (warning that a tag doesn't
exist and so on), but are removed, if empty, when building the Comment.

The only ones that stay even when empty are `@deprecated`, so that the
class name can be striked-through ("Deprecated" also appears in the
header, even if there is no message with it), and `@throws`.
@gourlaysama gourlaysama force-pushed the wip/t5795-scaladoc-empty-params branch from 3183c2b to 293f7c0 Compare April 2, 2015 18:15
@adriaanm
Copy link
Contributor

adriaanm commented Apr 6, 2015

The IDE job abort issue should be resolved now (scala/scala-jenkins-infra#44). I hit rebuild.

@gourlaysama
Copy link
Contributor Author

review by @VladUreche :)

@VladUreche
Copy link
Contributor

LGTM, thanks @gourlaysama!

@lrytz
Copy link
Member

lrytz commented Apr 9, 2015

Nice! Thanks guys :)

lrytz added a commit that referenced this pull request Apr 9, 2015
…rams

SI-5795 empty scaladoc tags should be omitted from output
@lrytz lrytz merged commit fedbfd7 into scala:2.11.x Apr 9, 2015
retronym pushed a commit to retronym/scala that referenced this pull request Jun 24, 2019
The implicit scope of a.A includes package object a. Document this.

Fixes scala#4427.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants