Add protected and private visibility filters to scaladoc

[exoego]

Closes scala/bug#10999

This PR adds Protected and Private visiblity filters.
Private filter is available only if scaladoc -private used, so user can omit private members to reduce scaladoc size.
Existing All is removed since it is no longer required.

[exoego]

Currently, visibility modifiers are shown inside a full comment, which is expanded if user clicked a member.
I think it would be more straightforward if visibility modifiers are shown always to the left of member., like final do so.
Anyway, I don't address this since it is a different topic.

[exoego]

Travis passed successfully, but checks on GitHub are not updated...

Could someone rerun Travis or perform something to resolve checks?

[lrytz]

Since we're now adding scaladocs for all private members, the doc size and the time to run scaladoc might grow significanlty.

Could you compare the scaladocs (size, time to generate) for the library and compiler, so we have an idea about the impact?

[lrytz]

I don't understand what the privateWithin check is for, can we remove it? As far as I know, privateWithin can be set in private[x] and protected[x]. The line excludes any private, and includes any protected, so the privateWithin seems useless, no? Maybe just try if all tests pass if you remove it.

[exoego]

Unfortunately, removing aSym.privateWithin == NoSymbol breaks the following tests.
(I have not investigated fully why broken)

[info] Elapsed time: 0.045 sec 
[info] ! HtmlFactory.scala/bug#8144: Members' permalink - inner package: Falsified after 0 passed tests.
[info] Elapsed time: 0.000 sec 
[info] ! HtmlFactory.scala/bug#8144: Members' permalink - companion object: Falsified after 0 passed tests.
[info] Elapsed time: 0.001 sec 
[info] ! HtmlFactory.scala/bug#8144: Members' permalink - class: Falsified after 0 passed tests.
[info] Elapsed time: 0.000 sec 
[info] ! HtmlFactory.scala/bug#9599 Multiple @todo formatted with comma on separate line: Falsified after 0 passed tests.
[info] Elapsed time: 0.063 sec 
[info] ! HtmlFactory.scala/bug#10999 Private and Protected method should also be documented: Falsified after 0 passed tests.

[lrytz]

Sorry, I was not very clear.. I pushed a change that simplifies localShouldDocument, hopefully that passes the tests.

[lrytz]

OK, here is my misunderstanding:

class C {
  private def a
  private[C] def b
  protected def c
  protected[C] def d
}

We get

	isPrivate	isProtected	privateWithin
a	true	false	NoSymbol
b	false	false	C
c	false	true	NoSymbol
d	false	true	C

Note that for b, isPrivate is false, but for d, isProtected is true.

[exoego]

Since we're now adding scaladocs for all private members, the doc size and the time to run scaladoc might grow significanlty.

Could you compare the scaladocs (size, time to generate) for the library and compiler, so we have an idea about the impact?

Summary (see below comparison for detail)

• Size increases 10-13%.
• Time-to-generate increases 7-8%.

Ofcourse these varies depending on how many private members in project, I think this is not so expensive for most projects.

Scala Library

mkdir docs
cd docs
time ../build/pack/bin/scaladoc   ../src/library/**/*.scala
du -K scala/

	no-private	private	diff
size (KB)	186468	205584	+10%
time to generate (s)	53.75	64.01
	55.7	62.03
	55.55	56.32
	54.11	55.48
	57.05	58
avg. (s)	55.232	59.168	+7%

Scala Compiler

mkdir docs
cd docs
time ../build/pack/bin/scaladoc   ../src/compiler/**/*.scala
du -K scala/

	no-private	private
size (KB)	93240	105200	+13%
time to generate (s)	46.03	46.72
	44.36	53.18
	45.7	46.99
	46.27	48.88
	46.74	52.78
avg. (s)	45.82	49.71	+8%

[lrytz]

Thank you for gathering these numbers. I think we should keep this PR open for discussion. Personally I don't see a good use case for listing private members in Scaladocs, so I'm not in favor. How about introducing a scaladoc option, e.g., -privates?

[SethTisue]

I don't see a good use case for listing private members in Scaladocs

is there a precedent, one way or the other, in Javadoc?

[exoego]

Javadoc can specify members to be included via the switch

• -public (public only)
• -protected (public + protected)
• -private (public + protected + private)

You can find switches via javadoc -help.

[exoego]

Some test (reflect/compile:doc) fails after 86f29be.

[error] - doc
[error]   - reflect/compile:doc failed: java.lang.IllegalArgumentException: 'type TreeCopier' isn't a class, trait or object thus cannot be built as a member template.
[error] java.lang.RuntimeException
[error] 	at $666274811a7807c56755$.$anonfun$root$26(build.sbt:955)
[error] 	at $666274811a7807c56755$.$anonfun$root$26$adapted(build.sbt:894)
[error] 	at scala.Function1.$anonfun$compose$1(Function1.scala:44)
[error] 	at sbt.internal.util.$tilde$greater.$anonfun$$u2219$1(TypeFunctions.scala:40)
[error] 	at sbt.std.Transform$$anon$4.work(System.scala:67)
[error] 	at sbt.Execute.$anonfun$submit$2(Execute.scala:269)
[error] 	at sbt.internal.util.ErrorHandling$.wideConvert(ErrorHandling.scala:16)
[error] 	at sbt.Execute.work(Execute.scala:278)
[error] 	at sbt.Execute.$anonfun$submit$1(Execute.scala:269)
[error] 	at sbt.ConcurrentRestrictions$$anon$4.$anonfun$submitValid$1(ConcurrentRestrictions.scala:178)
[error] 	at sbt.CompletionService$$anon$2.call(CompletionService.scala:37)
[error] 	at java.util.concurrent.FutureTask.run(FutureTask.java:266)
[error] 	at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:511)
[error] 	at java.util.concurrent.FutureTask.run(FutureTask.java:266)
[error] 	at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149)
[error] 	at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624)
[error] 	at java.lang.Thread.run(Thread.java:748)
[error] (testAll) java.lang.RuntimeException

[lrytz]

I'll take a look

[lrytz]

@exoego a -private seems to be a good solution. Could you do that?

[lrytz]

@exoego let us know if you still have time to work on this one!

[exoego]

@lrytz Added -private settings

[lrytz]

Thank you, @exoego!