Dropping package objects and documentation

Language Design
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.

2 Likes
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.

2 Likes
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…

1 Like
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…)

2 Likes
6

It suggested this topic to me, and now warns me that I’m going to be that guy where it says “one year later…”

Scala 3 has top-level defs and should also have top-level docs.

/** This package...
 */
package p {
}

Top-level doc which does not attach to a top-level def attaches to the empty package.

The docs for package p would be concatenated in the obvious way (in the order submitted to the tool, optionally with group headings derived from the file name).

The landing page for Scaladoc should not belong to a fictitious “root” package, but to the empty package.

This has the salutary effect of documenting any top-level defs which inadvertently find their way into the empty package, as for example if this issue is exploited.

Scaladoc could have a switch to turn empty packaging on or off, and a linter could also warn about a non-empty empty package. It is an “empty” package because its path is empty, but perhaps also because it should be empty of definitions before going to production?

3 Likes
7

So, now two years later, and with 3.2.0 around the corner, what’s the current situation? What’s the “official” word as to where we should move package object documentation?

3 Likes