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

Scaladoc does not add members of package objects to the method index #5558

Closed
scabug opened this issue Mar 8, 2012 · 18 comments
Closed

Scaladoc does not add members of package objects to the method index #5558

scabug opened this issue Mar 8, 2012 · 18 comments

Comments

@scabug
Copy link

scabug commented Mar 8, 2012

If you want to find the 'pow' method, for example, and you don't know where it is, you might go to the method index (i.e. the a-z index underneath the search field in the left frame). You click on 'p' and then look for 'pow'. You won't find it - ScalaDoc doesn't put members of package objects into this index.

Also:

Another thing which I realized while browsing through the index is the way in which the index entries are written, i.e. are capitalized.
Example: STAR: is defined in Trees.Star, Base.Star and Tokens.STAR, but listed in the index as STAR only. Probably all defined capitalizations could be listed on the index-title-line instead of only one (arbitrarily) chosen one. (noticed by Dominik)

@scabug
Copy link
Author

scabug commented Mar 8, 2012

Imported From: https://issues.scala-lang.org/browse/SI-5558?orig=1
Reporter: Derek Wyatt (derekwyatt)
Affected Versions: 2.9.1, 2.10.0-M2

@scabug
Copy link
Author

scabug commented Mar 8, 2012

@heathermiller said:
Right you are, sir.

Vlad, since this is in your realm of Scaladoc bugfixes, I'm tossing this one to you.

@scabug
Copy link
Author

scabug commented Mar 8, 2012

@VladUreche said:
Yes, that would be a nice improvement. But unless somebody comes up with a patch it's not likely I'll implement that soon -- i've already got my hands full with implicits.

So I'm bouncing this back to Documentation Team, hoping tomorrow it will rain patches ;)

@scabug
Copy link
Author

scabug commented Mar 8, 2012

@heathermiller said (edited on Mar 8, 2012 6:45:52 PM UTC):
Btw Vlad, I just looked at it-- in html/page/Index.scala, members of the package objects don't seem to be included in pack.templates (which is what's filtered and ultimately makes up the list of entries to be shown in the index pages): https://github.com/scala/scala/blob/master/src/compiler/scala/tools/nsc/doc/html/page/Index.scala#L64

So even if you ask for packages to be included in the filtered results, still no members of package objects show up.

@scabug
Copy link
Author

scabug commented Mar 8, 2012

@heathermiller said:
Regardless-- what's the issue with package objects being listed in the index? Is there a good reason they're filtered out?

@scabug
Copy link
Author

scabug commented Mar 8, 2012

@VladUreche said:
Can you come up with a small test case that I can use to debug it? I couldn't reproduce on trunk, the following example shows all members: package object Hello, object A and B:

package object Hello {
  object A
  object B
}

@scabug
Copy link
Author

scabug commented Mar 8, 2012

@heathermiller said (edited on Mar 8, 2012 7:00:51 PM UTC):
There's an example in nightly.

See scala.collection.parallel.package. Note the method setTaskSupport.

Then, navigate to the "S" index page: http://www.scala-http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library/index.html#index.index-s

There's no setTaskSupport method listed.

@scabug
Copy link
Author

scabug commented Mar 8, 2012

@VladUreche said:
Oh, that's expected. Methods, vals and vars don't appear in the index, since there's no page that corresponds to them. (In Scaladoc slang, they don't extend DocTemplateEntity)

@scabug
Copy link
Author

scabug commented Mar 8, 2012

Derek Wyatt (derekwyatt) said:
That's a problem :) When I was looking around, my question was "How does scala do x ** y?" Is it x ** y or x ^ y or x.power(y) or power(x, y), pow(x, y), etc...

NONE of these look up in the scaladoc. Thus... scala doesn't have this ability. Obviously that statement is incorrect, since math.pow() exists, but I can't find it unless I know that it's on the math package object already. But I didn't know that...

@scabug
Copy link
Author

scabug commented Mar 8, 2012

@heathermiller said:
Vlad, you sure that methods don't appear in the index? map certainly does: http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library/index.html#index.index-m

@scabug
Copy link
Author

scabug commented Mar 8, 2012

@heathermiller said:
Derek-- yep, being able to (easily) search for methods throughout the library is a feature that scaladoc is missing.

Though something that might be of use to you in general is http://scalex.org/. You can easily search for methods as well as anything with a non-alphabetic name pretty easily. Your original inquiry is more helpful here: http://scalex.org/?q=pow

It's something I'll integrate into the search bar on http://docs.scala-lang.org.

@scabug
Copy link
Author

scabug commented Mar 8, 2012

@dcsobral said:
Vlad, you are flat out wrong here. The index was made specifically to show methods.

@scabug
Copy link
Author

scabug commented Mar 8, 2012

@VladUreche said:
Okay, now I understand the problem. I was looking in the package index, not in the index itself.
Great, so I'm looking forward to merging the patch :)

@scabug
Copy link
Author

scabug commented Mar 25, 2012

@manojo said:
This issue is a bit trickier that it looks. The way the index is built, each DocTemplateEntity's members are added to the index, as long as the member's owner is the DocTemplateEntity in question (http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/compiler/index.html#scala.tools.nsc.doc.model.IndexModelFactory$).

Normally, the owner of a member is the template it is defined in, and this is computed with the makeTemplate function (by using the owner of the symbol of a member), where it will normally find a correspondence. In the case of a member of a package object, however, it seems that the owner of such a member does not correspond to the package, but to a generic symbol having the name "package"

TL;DR the symbol table does not seem to map owners correctly for members of package objects, so the issue seems to be during symbol table generation.

@scabug
Copy link
Author

scabug commented Apr 13, 2012

@dgruntz said:
Another thing which I realized while browsing through the index is the way in which the index entries are written, i.e. are capitalized.
Example: STAR: is defined in Trees.Star, Base.Star and Tokens.STAR, but listed in the index as STAR only. Probably all defined capitalizations could be listed on the index-title-line instead of only one (arbitrarily) chosen one.

Dominik

@scabug
Copy link
Author

scabug commented May 7, 2012

@magarciaEPFL said:
Now I hear that you're working on this bug, @manojo, if that's the case, unassigning it was my mistake! (Otherwise leave it unassigned, to better reflect reality, that's my take on it).

@scabug
Copy link
Author

scabug commented Jul 20, 2012

@adriaanm said:
scala/scala#925

@scabug scabug closed this as completed Jul 20, 2012
@scabug
Copy link
Author

scabug commented Jul 23, 2012

@VladUreche said:
Closed by the model rewrite in c11427c1.

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

2 participants