[scala-tools] Linking to methods in Scaladoc 2: not supported?

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

[scala-tools] Linking to methods in Scaladoc 2: not supported?

Daniel Dekany
You can't link to methods in Scaladoc 2, right? I tried
[[com.example.Class#method]], [[com.example.Class.method]],
[[com.example.Class.method()]] etc., and they just end up being plain
text in the HTML. Other projects that I have looked at either didn't
have links to methods or just used <a href="..."> instead of [[...]].

What I find rather strange is that there is no buzz regarding this...
or Google (and Trac) hates me. So what's up with this? Am I the only
one who thinks it's a fundamental limitation? Any hope it will be
fixed anytime soon, or is it some deeper problem with Scaladoc 2?

(Not reporting wrong links is horrible too... but at least I see
people complaining about that.)

--
Best regards,
 Daniel Dekany

Reply | Threaded
Open this post in threaded view
|

Re: [scala-tools] Linking to methods in Scaladoc 2: not supported?

Pedro Furlanetto
It has been discussed. The major limitation of a simple solution would
be ignoring alternatives of multiple overloaded methods. Would you
mind opening a Trac enhancement request? Depending on the feedback
from EPFL guys I may provide a implementation.

Cheers,
PF

2011/2/7 Daniel Dekany <[hidden email]>:

> You can't link to methods in Scaladoc 2, right? I tried
> [[com.example.Class#method]], [[com.example.Class.method]],
> [[com.example.Class.method()]] etc., and they just end up being plain
> text in the HTML. Other projects that I have looked at either didn't
> have links to methods or just used <a href="..."> instead of [[...]].
>
> What I find rather strange is that there is no buzz regarding this...
> or Google (and Trac) hates me. So what's up with this? Am I the only
> one who thinks it's a fundamental limitation? Any hope it will be
> fixed anytime soon, or is it some deeper problem with Scaladoc 2?
>
> (Not reporting wrong links is horrible too... but at least I see
> people complaining about that.)
>
> --
> Best regards,
>  Daniel Dekany
>
>
Reply | Threaded
Open this post in threaded view
|

Re: [scala-tools] Linking to methods in Scaladoc 2: not supported?

Daniel Dekany
Tuesday, February 8, 2011, 1:29:14 AM, Pedro Furlanetto wrote:

> It has been discussed. The major limitation of a simple solution would
> be ignoring alternatives of multiple overloaded methods.

Why is that a problem? JavaDoc solves this by allowing you to enter
the parameter types inside {@link ...} (or else it chooses arbitrarily
and issues a warning). Doesn't ScalaDoc re-use the relevant parts from
scalac? Scalac can already resolve such situations.

> Would you mind opening a Trac enhancement request?

Here it is:
https://lampsvn.epfl.ch/trac/scala/ticket/4224

> Depending on the feedback from EPFL guys I may provide a
> implementation.
>
> Cheers,
> PF
>
> 2011/2/7 Daniel Dekany <[hidden email]>:
>> You can't link to methods in Scaladoc 2, right? I tried
>> [[com.example.Class#method]], [[com.example.Class.method]],
>> [[com.example.Class.method()]] etc., and they just end up being plain
>> text in the HTML. Other projects that I have looked at either didn't
>> have links to methods or just used <a href="..."> instead of [[...]].
>>
>> What I find rather strange is that there is no buzz regarding this...
>> or Google (and Trac) hates me. So what's up with this? Am I the only
>> one who thinks it's a fundamental limitation? Any hope it will be
>> fixed anytime soon, or is it some deeper problem with Scaladoc 2?
>>
>> (Not reporting wrong links is horrible too... but at least I see
>> people complaining about that.)
>>
>> --
>> Best regards,
>>  Daniel Dekany
>>
>>
>

--
Best regards,
 Daniel Dekany

Reply | Threaded
Open this post in threaded view
|

Re: [scala-tools] Linking to methods in Scaladoc 2: not supported?

Aemon Cannon
In reply to this post by Pedro Furlanetto
+1
Would love to have this for ensime.

On Mon, Feb 7, 2011 at 4:29 PM, Pedro Furlanetto <[hidden email]> wrote:
It has been discussed. The major limitation of a simple solution would
be ignoring alternatives of multiple overloaded methods. Would you
mind opening a Trac enhancement request? Depending on the feedback
from EPFL guys I may provide a implementation.

Cheers,
PF

2011/2/7 Daniel Dekany <[hidden email]>:
> You can't link to methods in Scaladoc 2, right? I tried
> [[com.example.Class#method]], [[com.example.Class.method]],
> [[com.example.Class.method()]] etc., and they just end up being plain
> text in the HTML. Other projects that I have looked at either didn't
> have links to methods or just used <a href="..."> instead of [[...]].
>
> What I find rather strange is that there is no buzz regarding this...
> or Google (and Trac) hates me. So what's up with this? Am I the only
> one who thinks it's a fundamental limitation? Any hope it will be
> fixed anytime soon, or is it some deeper problem with Scaladoc 2?
>
> (Not reporting wrong links is horrible too... but at least I see
> people complaining about that.)
>
> --
> Best regards,
>  Daniel Dekany
>
>

Reply | Threaded
Open this post in threaded view
|

Re: [scala-tools] Linking to methods in Scaladoc 2: not supported?

Daniel Dekany
In reply to this post by Daniel Dekany
Tuesday, February 8, 2011, 1:53:37 AM, Daniel Dekany wrote:

> Tuesday, February 8, 2011, 1:29:14 AM, Pedro Furlanetto wrote:
>
>> It has been discussed. The major limitation of a simple solution would
>> be ignoring alternatives of multiple overloaded methods.
>
> Why is that a problem? JavaDoc solves this by allowing you to enter
> the parameter types inside {@link ...} (or else it chooses arbitrarily
> and issues a warning).

Actually, that's an annoying thing with JavaDoc... While the ability
to address a certain overload of a method is crucial, the ability to
address all the overloads at once is very often needed as well. So
ideally a link that doesn't specify the parameter types should pop up
a selection of all the overloads (unless one of the overload methods
was marked as the preferred overload). But, even if it just does what
JavaDoc does, that's already much better than the current situation.

> Doesn't ScalaDoc re-use the relevant parts from
> scalac? Scalac can already resolve such situations.
>
>> Would you mind opening a Trac enhancement request?
>
> Here it is:
> https://lampsvn.epfl.ch/trac/scala/ticket/4224
>
>> Depending on the feedback from EPFL guys I may provide a
>> implementation.
>>
>> Cheers,
>> PF
>>
>> 2011/2/7 Daniel Dekany <[hidden email]>:
>>> You can't link to methods in Scaladoc 2, right? I tried
>>> [[com.example.Class#method]], [[com.example.Class.method]],
>>> [[com.example.Class.method()]] etc., and they just end up being plain
>>> text in the HTML. Other projects that I have looked at either didn't
>>> have links to methods or just used <a href="..."> instead of [[...]].
>>>
>>> What I find rather strange is that there is no buzz regarding this...
>>> or Google (and Trac) hates me. So what's up with this? Am I the only
>>> one who thinks it's a fundamental limitation? Any hope it will be
>>> fixed anytime soon, or is it some deeper problem with Scaladoc 2?
>>>
>>> (Not reporting wrong links is horrible too... but at least I see
>>> people complaining about that.)
>>>
>>> --
>>> Best regards,
>>>  Daniel Dekany
>>>
>>>
>>
>

--
Best regards,
 Daniel Dekany

Reply | Threaded
Open this post in threaded view
|

[scala-tools] Re: Linking to methods in Scaladoc 2: not supported?

Philippe Lhoste
In reply to this post by Daniel Dekany
On 08/02/2011 00:21, Daniel Dekany wrote:

> You can't link to methods in Scaladoc 2, right? I tried
> [[com.example.Class#method]], [[com.example.Class.method]],
> [[com.example.Class.method()]] etc., and they just end up being plain
> text in the HTML. Other projects that I have looked at either didn't
> have links to methods or just used<a href="...">  instead of [[...]].
>
> What I find rather strange is that there is no buzz regarding this...
> or Google (and Trac) hates me. So what's up with this? Am I the only
> one who thinks it's a fundamental limitation? Any hope it will be
> fixed anytime soon, or is it some deeper problem with Scaladoc 2?

http://scala-programming-language.1934581.n4.nabble.com/A-criticism-of-ScalaDoc-output-td2715333.html

"The link to Scala classes like [[scala.collection.Set]] doesn't work (links to sites work)."
"I don't know if I must open one or several Trac tickets..."

Still waiting for an answer...

--
Philippe Lhoste
--  (near) Paris -- France
--  http://Phi.Lho.free.fr
--  --  --  --  --  --  --  --  --  --  --  --  --  --

Reply | Threaded
Open this post in threaded view
|

Re: [scala-tools] Re: Linking to methods in Scaladoc 2: not supported?

Daniel Dekany
Tuesday, February 8, 2011, 10:36:44 AM, Philippe Lhoste wrote:

> On 08/02/2011 00:21, Daniel Dekany wrote:
>> You can't link to methods in Scaladoc 2, right? I tried
>> [[com.example.Class#method]], [[com.example.Class.method]],
>> [[com.example.Class.method()]] etc., and they just end up being plain
>> text in the HTML. Other projects that I have looked at either didn't
>> have links to methods or just used<a href="...">  instead of [[...]].
>>
>> What I find rather strange is that there is no buzz regarding this...
>> or Google (and Trac) hates me. So what's up with this? Am I the only
>> one who thinks it's a fundamental limitation? Any hope it will be
>> fixed anytime soon, or is it some deeper problem with Scaladoc 2?
>
> http://scala-programming-language.1934581.n4.nabble.com/A-criticism-of-ScalaDoc-output-td2715333.html
>
> "The link to Scala classes like [[scala.collection.Set]] doesn't work (links to sites work)."
> "I don't know if I must open one or several Trac tickets..."

I suppose those should link to the API docs at http://scala-lang.org.

BTW, last night I have looked at VScalaDoc2 and noticed that it has
the same limitations regarding the links: links to methods (and to
scala-lang classes) will end up being plain text in the HTML output,
plus wrong links aren't reported. Maybe it builds on some of the
ScalaDoc2 API-s internally... I don't know.

> Still waiting for an answer...

It seems it's not just the Scala IDE support that needs a lot more
time to be there... I guess it's difficult to find a viable business
model that would support developing these things.

--
Best regards,
 Daniel Dekany

Reply | Threaded
Open this post in threaded view
|

Re: [scala-tools] Linking to methods in Scaladoc 2: not supported?

Paul Phillips-3
In reply to this post by Daniel Dekany
On 2/7/11 3:21 PM, Daniel Dekany wrote:
> You can't link to methods in Scaladoc 2, right? I tried
> [[com.example.Class#method]], [[com.example.Class.method]],
> [[com.example.Class.method()]] etc., and they just end up being plain
> text in the HTML. Other projects that I have looked at either didn't
> have links to methods or just used<a href="...">  instead of [[...]].

At some point I implemented repl help where tab completion would open a
web page with the scaladoc of the class or method being completed upon.
  At least, I implemented the part where a web page opens up, and then I
discovered I couldn't link to methods, so I shelved it.

However I never opened a ticket or anything so I don't have much
standing to complain.  Unless it's already open.  If it isn't open I bet
you know what to do.