Skip to content

SI-6626 make @throws tags create links to exceptions#4089

Merged
VladUreche merged 2 commits intoscala:2.11.xfrom
gourlaysama:wip/t6626-scaladoc-throws-links
Nov 5, 2014
Merged

SI-6626 make @throws tags create links to exceptions#4089
VladUreche merged 2 commits intoscala:2.11.xfrom
gourlaysama:wip/t6626-scaladoc-throws-links

Conversation

@gourlaysama
Copy link
Contributor

In scaladoc, this turns exceptions in @throws tags into links
(when it can find the target exception), instead of just showing
the name.

Review by @VladUreche :)

@scala-jenkins scala-jenkins added this to the 2.11.5 milestone Nov 4, 2014
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is a and b?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, those are pretty unclear; fixed.

@gourlaysama gourlaysama force-pushed the wip/t6626-scaladoc-throws-links branch from e699fcb to 250551b Compare November 4, 2014 15:22
@VladUreche
Copy link
Contributor

@gourlaysama, seems the new method prevents the presentation compiler from being compiled:

fail - presentation/doc  [compilation failed]% scalac doc/doc.scala
doc.scala:42: error: object creation impossible, since method linkName in trait MemberLookupBase of type (link: scala.tools.nsc.doc.base.LinkTo)String is not defined
    new Global(settings, compilerReporter) with MemberLookupBase with CommentFactoryBase with doc.ScaladocGlobalTrait {
        ^

(see https://scala-webapps.epfl.ch/jenkins/job/pr-scala-test/7400/console)

Can you please address this?

@gourlaysama gourlaysama force-pushed the wip/t6626-scaladoc-throws-links branch 2 times, most recently from 3af3360 to f03c102 Compare November 5, 2014 10:16
@gourlaysama
Copy link
Contributor Author

@VladUreche sorry about that. I should have asked for review after jenkins was finished.

I just realized this will break scala-ide too, for the same reason as above: it needs to implement that method to do the right thing...

In scaladoc, this turns exceptions in @throws tags into links
(when it can find the target exception), instead of just showing
the name.
 - there is no need for explicit links with [[ and ]]
 - there is no need for explicit backquoting
@gourlaysama gourlaysama force-pushed the wip/t6626-scaladoc-throws-links branch from f03c102 to 9d0d44c Compare November 5, 2014 13:50
@VladUreche
Copy link
Contributor

LGTM! Now that the build passes, I can merge. Thanks @gourlaysama!

VladUreche pushed a commit that referenced this pull request Nov 5, 2014
…inks

SI-6626 make @throws tags create links to exceptions
@VladUreche VladUreche merged commit cd50464 into scala:2.11.x Nov 5, 2014
@gourlaysama gourlaysama deleted the wip/t6626-scaladoc-throws-links branch November 12, 2014 14:09
@lrytz
Copy link
Member

lrytz commented May 14, 2015

Hi, question about this change: it seems that we get a warning now whenever writing @throws E and E is on the classpath, not in the project being compiled. I guess that's not intended?

lucmac:sandbox luc$ cat Test.scala 
class A {
  /**
   * @throws Exk bla
   * @throws java.lang.Exception
   */
  def foo = 1
}
class Exk extends Exception

lucmac:sandbox luc$ ~/scala/scala-2.11.6/bin/scaladoc Test.scala 
model contains 3 documentable templates
Test.scala:2: warning: Could not find any member to link for "java.lang.Exception".
  /**
  ^
one warning found

see https://issues.scala-lang.org/browse/SI-9311

@VladUreche
Copy link
Contributor

@lrytz: Yes, it's expected: https://github.com/scala/scala/pull/4089/files#diff-cf5321b0df0af2c25cec233dbb01cc20R352

Ifneedbe we can silence the warning.

@lrytz
Copy link
Member

lrytz commented May 15, 2015

I think we should skip the warning for exception classes that are out of the project, it's not so nice to have warnings that you cannot get rid of.

@VladUreche
Copy link
Contributor

@gourlaysama, can you take care of this? Or should I do it?

@gourlaysama
Copy link
Contributor Author

@VladUreche Yep I'll take that one. Warnings that aren't actionable are useless...

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