Consider how to document packages when there's no package object

[abgruszecki]

Note: package objects are not deprecated, we could just require a package object as the place to have package documentation?

[BarkingBad]

Kotlin uses includes to provide description for modules/packages. Formatting is simple and intuitive, however, I think enforcing empty package object when you need to document package is not an abuse.

https://github.com/Kotlin/kotlin-examples/tree/master/gradle/dokka/dokka-gradle-example
here is sample project with Module.md file for content and in build.gradle.kts include.from for providing it to documentation

[smarter]

In https://contributors.scala-lang.org/t/dropping-package-objects-and-documentation/2942 I suggested we use README.md in the directory corresponding to the packages to do this, there were a few other proposals too.

[Facsimiler]

I guess one problem that I would have with a Markdown file, such as README.md, is that there is no place for ScalaDoc tags such as @since, @example, @note, @define, @see, etc. Code reference links, and integration with the rest of the program's ScalaDoc, would also become more complicated. Any ideas for how we could include those in a Markdown file?

From that perspective, I would prefer the approach used by Java, as mentioned by Seth Tisue in the discussion link above, in which a ScalaDoc comment is placed before the package declaration in, say, package.scala (or package-info.scala). There's then no need to be concerned about the different Markdown syntax, code references, etc. and tags are possible.

[smarter]

Nothing prevents us from putting scaladoc tags in markdown files, in fact scala3doc already supports both markdown and wiki syntax in scaladoc comments.

[Facsimiler]

I accept that is possible to put Markdown in a ScalaDoc comment, but wouldn't there be issues putting ScalaDoc links and tags in a Markdown file? These files are not typically processed as ScalaDoc, so you would need to create (yet) another flavor of Markdown that includes ScalaDoc-style links and tags, right? For example, if you edited such Markdown files in an IDE, then it would need to know that it was a flavor that supports features of ScalaDoc.

Also, it would confusing to browse the sources here on GitHub, GitLab, BitBucket, etc. which would fail to correctly parse any Markdown files containing ScalaDoc-specific syntax. A project with a README.md file in the root folder (that provides information about the project) would have a different Markdown syntax to those containing package documentation, causing further confusion.

Another problem I foresee is this: if the package documentation is in a package.scala file, as a ScalaDoc comment, then it is clearly a source file and would be treated as such; that's less obviously the case with a README.md file, which looks like something else entirely.

Thoughts?

[smarter]

I mean, I don't care that much, I just proposed using README.md so that it gets auto-displayed in github/gitlab, the scaladoc @foo tags would just be displayed as plain text which is good enough.

[BarkingBad]

I can implement README.md solution that cotnains Scaladoc specific syntax to have auto-display in github/gitlab, yet be able to pass param tags. e. g. @author. However, there have to be some header to the file that points to specific package, since directory tree does not have to represent actual packages hierarchy.

Most straight forward solution is to have package fq name in the very first line. So for package foo.bar we'd have following README.md file containing:

foo.bar
Here is description for package foo.bar
@author My Name

these READMEs are not available in TASTY, so everything would be convention to gather all files in src directory called README.md and then associate them with specific packages by the fq name they provide in first line.

What do you think about that @smarter @Facsimiler @romanowski @abgruszecki?

[abgruszecki]

We want to be able to generate documentation from already published artifacts. We also want to be able to view documentation in the REPL. This means that if we want to support those README.md files, we'd need to package them in the jars. If we load them from the jars, then directory structure matches package structure. This means that it's the build tool that should resolve which package a README.md file documents.

Perhaps the morally correct thing to do would be to use an XML processing directive like <?package foo.bar?> to define which package a README.md file documents? This should play well with anything that processes Markdown.

I guess there's also the matter that we may not want to collide with any resource files that a user needs to insert into the .jar.

[BarkingBad]

The problem is, every build tool should support our new convention to package these READMEs. Or should we support only sbt and assume that it is user responsibility to manage these READMEs be shipped in jars?

[ekrich]

Is it possible to just have a package.md or package.html, package-info.scala like Java for this?
I don't think this is a great solution because it requires special build support - https://stackoverflow.com/questions/16644948/where-does-scaladoc-look-for-the-rootdoc-txt-to-create-the-root-doc
The other thing is that is would be great to have a format other than text so you can have some tools support.