SI-9620: add doc annotation to hide specific conversions #4952

felixmulder · 2016-02-08T18:34:00Z

This commit will introduce the doc annotation @hideImplicitConversion.
By specifying which conversions to hide, the user can "toggle" which
conversions are shown be default.

This implementation is a better workaround than hardcoding which ones to
ignore when running scaladoc.

An example of how to use this:

package a

trait Foo[S] {
  def foo(t: S): Int = 123
}

/** Boo with only one foo method, hopefully!
 * @hideImplicitConversion BooShouldNotAppearIsFoo
 */
trait Boo[T]

object Boo {
  sealed trait ShouldNotAppear
  implicit class BooShouldNotAppearIsFoo(boo: Boo[ShouldNotAppear]) extends Foo[ShouldNotAppear]
  implicit class BooLongIsFoo(boo: Boo[Long]) extends Foo[Long]
}

Review: @VladUreche

felixmulder · 2016-02-09T10:23:42Z

All right - updated with your input @VladUreche

VladUreche · 2016-02-09T11:12:51Z

Thanks for the quick update Felix and sorry for my belated answers.

Thinking more about this, I'm not sure it will eliminate the Array problem. The reason is that it hides the implicit conversions at the very last moment, when the html is generated. But the JSON is still generated with the multiple members.

At the moment, I guess your previous PR which amended the hardcoded object masks this problem. But I expect once you remove the hardcoding, you will see the duplicate methods in search again.

So, the way I think this should work is to prune the implicit conversions directly in ModelFactoryImplicitSupport, before any implicitly added members are created for the current entity. WDYT?

felixmulder · 2016-02-09T11:18:48Z

Damnit, you're right!

Regarding pruning in ModelFactoryImplicitSupport, this will remove the entries completely. Are we fine with that? I mean - the current solution in this PR hides them from view - pruning them in ModelFactoryImplicitSupport will completely remove them.

So IMO there are two options:

Prune in ModelFactoryImplicitSupport (they won't show up)
Keep the current implementation, but also prune in IndexScript.scala where the JSON is generated (they won't show up in search, but will be toggle-able on the entity page)

WDYT?

VladUreche · 2016-02-09T11:26:17Z

Yes, both solutions do the trick. Though I'm more in favor of the ModelFactoryImplicitSupport one, which looks more principled.

felixmulder · 2016-02-09T11:30:10Z

All right - then I'll go for # 1 👍

felixmulder · 2016-02-09T13:20:51Z

At first I thought I couldn't get the comment from the ModelFactoryImplicitSupport class - then I noticed the thisFactory variable and the party was back on 🎉

This should be along the lines of what you intended for the implementation @VladUreche

felixmulder · 2016-02-09T13:24:26Z

Pulled changes from upstream into my branch - once it's been through Jenkins it should be good to go.

VladUreche · 2016-02-09T13:47:24Z

@felixmulder great! Can you please add a test case on this?
You can use this as a template: https://github.com/scala/scala/blob/2.12.x/test/scaladoc/run/SI-3448.scala

VladUreche · 2016-02-09T14:27:03Z

Maybe a good think to test is that adding this annotation to Array and un-hardcoding the implicit conversions to be ignored produces the right scaladoc output.

felixmulder · 2016-02-09T14:32:21Z

I've added the test and I'll look at Array now. Will ping you once I know that everything's working 😄

VladUreche · 2016-02-09T14:44:06Z

👍

felixmulder · 2016-02-09T15:44:17Z

Ok - so this is where I'm at. I've added the annotation to the Array class. Removed the hardcoded ignores from the Settings.scala file in scaladoc. I've created a test for SI-9620.

It generates the Array documentation without the implicits, huzzah! 🎉

HOWEVER! I can't get my stupid test to work 😢

@VladUreche

felixmulder · 2016-02-09T15:47:24Z

test/scaladoc/run/SI-9620.scala

+    // Assert Boo only has one implicit conversion
+    val boo = rootPackage._package("a")._trait("Boo")
+    val conversions = boo._conversions("a.Boo.BooShouldNotAppearIsFoo") ++ boo._conversions("a.Boo.BooLongIsFoo")
+    assert(conversions.length == 1, conversions.length + " == 1")


@VladUreche: the length here is 0 for some reason. I also checked boo.conversions.length which is 0.

I think it's probably the fact that -implicits is not set in the scaladoc flags.

Yep, most likely. Here's a test for implicits:
https://github.com/scala/scala/blob/2.12.x/test/scaladoc/run/implicits-known-type-classes.scala#L11

@VladUreche

This commit will introduce the doc annotation `@hideImplicitConversion`. By specifying which conversions to hide, the user can "toggle" which conversions are kept in the parsed entity. This implementation is a better workaround than hardcoding which ones to ignore when running scaladoc. Review: @VladUreche

felixmulder · 2016-02-09T16:17:29Z

@VladUreche thanks so much! It works 😄 Thanks a bunch for the help!

Squished and commited!

VladUreche · 2016-02-09T16:21:59Z

LGTM, thanks a lot for your tireless work @felixmulder!
Ping @janekdb: can you please add the hideImplicitConversion to the scaladoc tutorial?

janekdb · 2016-02-09T18:18:12Z

@VladUreche : Added to pending list on scala/scala-lang#394

…Conversions-tag SI-9620: add doc annotation to hide specific conversions

VladUreche · 2016-02-09T18:28:36Z

👍

scala-jenkins added this to the 2.12.0-M4 milestone Feb 8, 2016

felixmulder force-pushed the topic/scaladoc-hideImplicitConversions-tag branch from 130b5e7 to 1076700 Compare February 9, 2016 10:21

felixmulder force-pushed the topic/scaladoc-hideImplicitConversions-tag branch from 1076700 to 0fbee29 Compare February 9, 2016 13:17

felixmulder force-pushed the topic/scaladoc-hideImplicitConversions-tag branch from 0fbee29 to a25817e Compare February 9, 2016 13:23

felixmulder reviewed Feb 9, 2016
View reviewed changes

felixmulder force-pushed the topic/scaladoc-hideImplicitConversions-tag branch from b181782 to f2e0616 Compare February 9, 2016 16:16

scala-jenkins added the reviewed label Feb 9, 2016

VladUreche pushed a commit that referenced this pull request Feb 9, 2016

Merge pull request #4952 from felixmulder/topic/scaladoc-hideImplicit…

b0beb72

…Conversions-tag SI-9620: add doc annotation to hide specific conversions

VladUreche merged commit b0beb72 into scala:2.12.x Feb 9, 2016

SethTisue added the release-notes worth highlighting in next release notes label Feb 9, 2016

adriaanm added 2.12.0 and removed 2.12 labels Oct 29, 2016

adriaanm added the 2.12 label Oct 29, 2016

lrytz mentioned this pull request Nov 1, 2016

notes on possible 2.12 release notes improvements scala/make-release-notes#202

Closed

16 tasks

scabug mentioned this pull request Apr 7, 2017

Scaladoc implicits: multiple conversions may lead to duplicate members scala/bug#9620

Closed

SI-9620: add doc annotation to hide specific conversions #4952

SI-9620: add doc annotation to hide specific conversions #4952

Uh oh!

Conversation

felixmulder commented Feb 8, 2016

Uh oh!

felixmulder commented Feb 9, 2016

Uh oh!

VladUreche commented Feb 9, 2016

Uh oh!

felixmulder commented Feb 9, 2016

Uh oh!

VladUreche commented Feb 9, 2016

Uh oh!

felixmulder commented Feb 9, 2016

Uh oh!

felixmulder commented Feb 9, 2016

Uh oh!

felixmulder commented Feb 9, 2016

Uh oh!

VladUreche commented Feb 9, 2016

Uh oh!

VladUreche commented Feb 9, 2016

Uh oh!

felixmulder commented Feb 9, 2016

Uh oh!

VladUreche commented Feb 9, 2016

Uh oh!

felixmulder commented Feb 9, 2016

Uh oh!

felixmulder Feb 9, 2016

Choose a reason for hiding this comment

Uh oh!

VladUreche Feb 9, 2016

Choose a reason for hiding this comment

Uh oh!

VladUreche Feb 9, 2016

Choose a reason for hiding this comment

Uh oh!

felixmulder commented Feb 9, 2016

Uh oh!

VladUreche commented Feb 9, 2016

Uh oh!

janekdb commented Feb 9, 2016

Uh oh!

VladUreche commented Feb 9, 2016

Uh oh!

Uh oh!