Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

support non-fully-qualified type links in scaladoc comments #3695

Open
scabug opened this issue Jul 22, 2010 · 17 comments
Open

support non-fully-qualified type links in scaladoc comments #3695

scabug opened this issue Jul 22, 2010 · 17 comments

Comments

@scabug
Copy link

scabug commented Jul 22, 2010

Given that scala has powerful imports, plus we can rename/alias types, it would be great if we could just use the same name/expression for types in scaladoc comments as we use in the code - rather than having to use fully qualified names in link.

e.g.

/** something [[List]] */

rather than

/** something [[scala.collection.immutable.List]] */
@scabug
Copy link
Author

scabug commented Jul 22, 2010

Imported From: https://issues.scala-lang.org/browse/SI-3695?orig=1
Reporter: James Strachan (jstrachan)
Affected Versions: 2.10.3, 2.11.0

@scabug
Copy link
Author

scabug commented Jul 20, 2012

@adriaanm said:
scala/scala#925

@scabug
Copy link
Author

scabug commented Jul 23, 2012

@VladUreche said (edited on Jul 23, 2012 11:19:11 AM UTC):
We will have a complete scaladoc tutorial on [http://docs.scala-lang.org] shortly. Until then, citing the scaladoc tool:

Quick crash course on using Scaladoc links
==========================================
 - Links relative to the current template should work. Make sure to use fully qualified names 
if the member is inherited into other templates or is inherited by implicit conversions (as 
they will be expanded relative to the containing template)
Disambiguating terms and types: Prefix terms with '$' and types with '!' in case both names are in use:
 - [[scala.collection.immutable.List!.apply class List's apply method]] and
 - [[scala.collection.immutable.List$.apply object List's apply method]]
Disambiguating overloaded members: If a term is overloaded, you can indicate the first part of its signature followed by *:
 - [[[scala.collection.immutable.List$.fill[A](Int)(?A):List[A]* Fill with a single parameter]]]
 - [[[scala.collection.immutable.List$.fill[A](Int,Int)(?A):List[List[A]]* Fill with a two parameters]]]
Notes: 
 - you can use any number of matching square brackets to avoid interference with the signature
 - you can use \. to escape dots in prefixes (don't forget to use * at the end to match the signature!)
 - you can use \# to escape hashes, otherwise they will be considered as delimiters, like dots.

Another crash course on links: [http://www.slideshare.net/VladUreche/scaladoc-reflection/17]

@scabug
Copy link
Author

scabug commented Oct 16, 2013

Bruno Bieth (mustaghattack) said:

As of scala 2.10.3 the following doesn't work for me:

package a

class A {
  def nice() {}
  def nice(s: String) {
  }
}

class B {
  /**
   * A link to [[A.nice(String)]]
   * @see [[A.nice(String)]]
   */
  def ooh() {

  }
}

I get

methodlink.scala:10: warning: Could not find any member to link for "A.nice(String)".
  /**
  ^
one warning found

Are method links a work in progress? Should I fill a bug report?

About the documentation..
How can you get the "Quick crash course" from the scaladoc tool? I couldn't find any command line option to trigger it.
It would also be nice to have a direct link to the documentation, but it seems it has not been written yet?

Thanks

@scabug
Copy link
Author

scabug commented Oct 16, 2013

@VladUreche said:
Bruno, I added Eugene Vigdorchik to the watchers list, I hope he knows a bit more than I do about the latest developments in links. And yes, the documentation (http://docs.scala-lang.org/overviews/scaladoc/basics.html) is pending for a year now, but I never got around to writing it -- feel free to open a bug for the documentation and one for the crash course.

Also, regarding the problem you're facing, did you try A.nice(s: String)?

@scabug
Copy link
Author

scabug commented Oct 17, 2013

Bruno Bieth (mustaghattack) said:
Using A.nice(s: String) here is what I get:

methodlink.scala:10: warning: Could not find any member to link for "A.nice(s:".
  /**
  ^
one warning found

@scabug
Copy link
Author

scabug commented Dec 7, 2013

Eric Pederson (ericacm) said:
Is it possible to link to a constructor?

@scabug
Copy link
Author

scabug commented Dec 10, 2013

@VladUreche said:
Bruno, try A.nice(s:String) (no spaces). I reopened the bug because it should give the error message and it should accept spaces.
Eric, no, it's not possible to link to the constructor. Link to the class instead. Or open a bug for this.

@scabug
Copy link
Author

scabug commented Dec 10, 2013

@VladUreche said:
Issues that need solving:

  • tutorial doesn't appear
  • spaces should be accepted in links

@scabug
Copy link
Author

scabug commented Dec 10, 2013

@adriaanm said:
Could you set the fix-by version to something in the future? :-)

The most important fields for planners: assignee, affected version, fix-by versions.
Issues that are unassigned and have no fix-by version are considered "unread".
When an issue is read, it should be: assigned || (scheduled for an upcoming release || marked as fix-by backlog).

Fix by backlog means we're not planning to work on this in the near future.

@scabug
Copy link
Author

scabug commented Dec 11, 2013

Eric Pederson (ericacm) said:
Done - #8067. Thanks!

@scabug
Copy link
Author

scabug commented Dec 11, 2013

Bruno Bieth (mustaghattack) said:
None of the three work:

method-link.scala:10: warning: Could not find any member to link for "A.nice(String)".
  /**
  ^
method-link.scala:18: warning: Could not find any member to link for "A.nice(s:".
  /**
  ^
method-link.scala:26: warning: Could not find any member to link for "A.nice(s:String)".
  /**
  ^
three warnings found

@scabug
Copy link
Author

scabug commented Jul 18, 2014

Alan Johnson (acjohnson55) said:
I can't get basic non-fully qualified type links working. I get warnings when trying to use shorthand references to names from wildcard imports, explicit imports, and the standard library. It's extremely frustrating having to type out fully qualified names in the docs, because for my project, the docs are read in code more so than they are in the generated HTML. I really hope we can get this basic functionality fixed. Maybe even an option to auto-import a package prefix would be helpful.

@scabug
Copy link
Author

scabug commented Jul 18, 2014

@VladUreche said:
I agree that's a nasty limitation: you can have links relative to the current template, but not relative to imports. Can you please create a bug for this?

@scabug
Copy link
Author

scabug commented Jul 18, 2014

Alan Johnson (acjohnson55) said:
Yep: #8734

Thanks!

@LDVSOFT
Copy link

LDVSOFT commented Jul 13, 2020

Any chance on progress here?

@SethTisue SethTisue added this to the Backlog milestone Jul 22, 2020
@SethTisue
Copy link
Member

@LDVSOFT in Scala 2, this is highly unlikely to ever be addressed by the core team. perhaps you or another volunteer would like to tackle it.

in a Scala 3 context, you might look into whether Dottydoc and/or Tastydoc (see scala/scala3#7668) have the same limitation

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants