Steve Lawrence created DAFFODIL-3012:
----------------------------------------
Summary: Unidoc generation broken in scala3
Key: DAFFODIL-3012
URL: https://issues.apache.org/jira/browse/DAFFODIL-3012
Project: Daffodil
Issue Type: Bug
Components: Infrastructure
Affects Versions: 4.0.0
Reporter: Steve Lawrence
Fix For: 4.0.0
Running sbt unidoc on the lastest main branch does not generate any
documentation.
I think the issue is that sbt-unidoc uses the {{tastyFiles}} setting instead of
the {{sources}} setting when building with Scala 3:
https://github.com/sbt/sbt-unidoc/blob/develop/src/main/scala/sbtunidoc/ScalaUnidocPlugin.scala#L34-L41
It does not look like tasty files are created for .java files, so our
apiDocSettings filter causes unidocAllSources to be empty, and we do not
generate any documentation.
A fix could be to reimplement unidocAllSources to use non-scala3 logic so .java
files are included, e.g.:
{code:scala}
ScalaUnidoc / unidoc / unidocAllSources := Def.taskDyn {
val scopeFilter = (ScalaUnidoc / unidoc / unidocScopeFilter).value
sources.all(scopeFilter)
}.value.map(apiDocSourceFilter)
{code}
And that *should* get us generating javadoc again since it will only include
/src/main/java/ files, which does not include any .scala or .tasty files and
will use javadoc to generate docs.
However, it's not clear to me if we can generate scaladoc as well. We have a PR
that adds a dummy.scala file and reruns sbt unidoc:
https://github.com/apache/daffodil-site/pull/183
But I think that only works on scala 2 to generate scaladoc. It seems like
Scala3 scaladoc only works on .tasty files and ignores .java files completely,
even if they are part of the public API. I can't find any mention of this
behavior, but simple tests with a single .java and .scala file do not include
any documentation about the java class.
We could maybe add the dummy.scala file and change scalaVersion to 2.13
temporarily only when building docs, but I imagine that would mean we would
still need to support scala 2.13 (even if we don't publish 2.13), which we
don't really want to do.
We may need to just drop the scaladoc view of the Daffodil API, and update our
site to only include javadoc if scaladoc3 does not have a way to include Java
files in the scaladoc documentation.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
