Dropping package objects and documentation

#1

I’m currently documenting a project and noticed two things:

  • The improved scaladoc interface does not list package members any more in the values of a particular package.

  • With package objects being dropped in Dotty, the package object documentation comments do not have a place to go.

  • Finally, there is the weird inconsistency of having the root documentation in a text file pointed to by the -doc-root-content scaladoc key.

Right now, Scala does not prescribe a particular directory structure for source files; thus, we cannot prescribe that each package directory should contain a scaladoc.txt text file (as in src/main/scaladoc.txt, src/main/scala/scaladoc.txt, src/main/scala/collection/scaladoc.txt, …)

I wonder what a solution could look like.

1 Like
#2

How about teaching scaladoc/dottydoc to recognize README.md in package directories ? This way the information is also displayed when browsing with github for example.

#3

That’s true, but I think it’s fine to require that this convention be followed to get proper documentation generation.

#4

Huge +1 to this – this is a good de-facto standard already, and making it de-jure seems like a total win in my book…

#5

Java has a convention for this already: https://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#packagecomment

If we follow this, it’d be package-info.scala, I guess. (Unless we just stick with package.scala…)

1 Like