[
https://issues.apache.org/jira/browse/DAFFODIL-3012?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Steve Lawrence updated DAFFODIL-3012:
-------------------------------------
Description:
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.
Another alternative is maybe to convert our java files to .scala or .tasty
files just for document generation (essentially the opposite of what genjavadoc
does which converts .scala files to .java files), but from what I can tell
nothing like that exists.
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.
was:
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.
> 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
> Priority: Major
> 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.
> Another alternative is maybe to convert our java files to .scala or .tasty
> files just for document generation (essentially the opposite of what
> genjavadoc does which converts .scala files to .java files), but from what I
> can tell nothing like that exists.
> 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)
