Encourage Scaladocs for Typelevel Projects

[alexandru]

It's great that type-checked documentation is required for Typelevel projects, but full membership should also require, or at least encourage good Scaladocs.

There is a certain aversion for API docs. Some are good arguments, some are bad, but the points I see in favour of Scaladoc are:

1. Easy to search / navigate when wondering about a certain type
2. Gets distributed / downloaded along with the library JARs
3. Exposed by IDEs like IntelliJ IDEA
4. Java developers are accustomed to API docs

As a final note, the competition for Typelevel libraries isn't really Scalaz in my opinion, but rather Java libraries, such as this one: http://reactivex.io/RxJava/2.x/javadoc/ - and in terms of documentation, these Java projects really set a high standard.

And there are also Scala projects doing a really good job. For example: http://doc.scalatest.org/3.0.0/index.html

[rossabaker]

There are compiler plugins and sbt plugins for which scaladoc makes little sense. I also wouldn't turn away a library that had a comprehensive tut. I think it's a great suggestion for most libraries, but I wouldn't make it a hard requirement.

[tpolecat]

I kind of disagree with (1) above. Scaladoc is ok for class-based libraries but it doesn't really understand the pattern of FP that are common in the code that I write (typeclasses, ADTs, modules of functions, partial type application, type aliasing, etc.), and the resulting Scaladoc is pretty crappy no matter what I do. And I have put some effort into it. So I think this is a nice to have but shouldn't be a requirement because some designs make it impossible.

With some luck a scala.meta will open the door to better tooling that can understand what I'm doing.

[alexandru]

OK, maybe requiring is a too strong requirement, but lets say strong encouragement. Personally I'd love to see more Scaladocs.

I think the Scaladoc tooling is in a sad state where it's good enough, if you're willing to suffer its problems. You end up working with sbt-unidoc and search the internet for tribal knowledge on its syntax.

But given that Typelevel now maintains a compiler fork, it's not unreasonable to hope for better Scaladoc tooling 😄

I would also love a tut for Scaladoc, if anybody knows an alternative, please share.

[ghost]

I would also love a tut for Scaladoc, if anybody knows an alternative, please share.

Do you mean something like sbt-doctest, eg as used in cats

[rossabaker]

Still a good idea, not a mandate. Closing for inactivity.