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: hide complex definitions behind use cases #5054

Closed
scabug opened this issue Oct 4, 2011 · 11 comments
Closed

Scaladoc: hide complex definitions behind use cases #5054

scabug opened this issue Oct 4, 2011 · 11 comments
Assignees

Comments

@scabug
Copy link

scabug commented Oct 4, 2011

Scaladoc: hide complex definitions behind use cases rather than showing both the complex definition and use cases

@scabug
Copy link
Author

scabug commented Oct 4, 2011

Imported From: https://issues.scala-lang.org/browse/SI-5054?orig=1
Reporter: @VladUreche

@scabug
Copy link
Author

scabug commented Nov 22, 2011

Commit Message Bot (anonymous) said:
(ureche in r26048) Changed the way use cases are handled in scaladoc.

If use cases are present, the original member disappears from the list. References #5054, but needs more work on the html part.
If use cases are present along with links, scaladoc doesn't crash anymore. Closes #4898.

Review by kzys.

@scabug
Copy link
Author

scabug commented Nov 23, 2011

@soc said:
There are multiple problems with the current approach, for instance have look at http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library/index.html#scala.collection.immutable.List ++::

  • The whole body with the example is missing
  • The type descriptions refer to types not present in the simplified signature
  • Use cases are still shown as abstract
  • The “real” method TraversableLike is mentioned as the definition class, but the signatures don't even match

I'm not sure all problems are solvable with the current design.

@scabug
Copy link
Author

scabug commented Nov 23, 2011

@VladUreche said:
Thanks for pointing them out Simon!

1 - Yes, the whole body with the signature and example will appear inside the use case (this is just a partial fix)
2 - Indeed, that's a nuisance, we'll have to figure out how to fix it (either in the explanation or automatically transform the comment)
3 - Was that happening before? I think it was introduced by my change, will dig more into this.
4 - Right. Should be fixed by the same patch as 1, as we'll show the full signature for the member and the full explanation.

@scabug
Copy link
Author

scabug commented Nov 23, 2011

@soc said:
3 - I don't think it was introduced by you (I have certainly seen it before), but I'm not quite sure ...

@scabug
Copy link
Author

scabug commented Nov 23, 2011

@soc said:
Maybe it would be possible to add some explanation with links to every usage of CanBuildFrom in the docs.

I think that would be really the key improvement if people could easily read and understand

  • why we show only the simplified signatures
  • why this is a good idea
  • what actual benefit the more complex signature brings to the table.

I think a @notice with some ScalaDoc macro could do that...

@scabug
Copy link
Author

scabug commented Nov 29, 2011

@dcsobral said:
The methods are being shown as "abstract". Also... how can I see the actual signature? I see Simon complaining that the signature shows up in the body, but I don't see it at all!

@scabug
Copy link
Author

scabug commented Nov 29, 2011

@VladUreche said:

  • I looked into the abstract use cases problem and it was always like this -- see [the 2.9.1 scaladoc|http://www.scala-lang.org/api/current/index.html#scala.collection.immutable.List] for List, the ++ use case has Attributes: abstract, but it's not shown in the signature. We can hide them again, no problem :)
  • the full signature is contained in the model, but the html generation needs a bit of tweaking to show it

@scabug
Copy link
Author

scabug commented Nov 29, 2011

@dcsobral said:
Actually, I know, but the actual method wasn't hidden then. At any rate, the method in the use case does not exist, so no attributes makes sense for it. Instead, it should assume the attributes of the method it is actually "overriding", so to speak.

@scabug
Copy link
Author

scabug commented Dec 8, 2011

@VladUreche said:
Fixed in pull request 46.

@scabug
Copy link
Author

scabug commented Jul 23, 2012

@VladUreche said:
Fixed everything some time ago, the only piece missing from the puzzle is #5291.

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