This is an automated email from the ASF dual-hosted git repository.
mbeckerle pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/daffodil.git
The following commit(s) were added to refs/heads/main by this push:
new d21ddd8e2 Enable javadoc and scaladoc from runtime1 API
d21ddd8e2 is described below
commit d21ddd8e2e104f84c8c33f26113d6f468ed2d6d0
Author: Michael Beckerle <[email protected]>
AuthorDate: Tue May 14 10:12:30 2024 -0400
Enable javadoc and scaladoc from runtime1 API
This commit is not about the content of that javadoc nor scaladoc, but
about the build.sbt and other changes to enable API doc from things
other than our JAPI and SAPI modules.
Note bug DAFFODIL-2902 because we are unable to create
proper javadoc from runtime1/api/Metadata.scala and
runtime1/api/Infoset.scala.
DAFFODIL-2900
---
build.sbt | 92 ++++++++++++++++------
daffodil-japi/build.sbt | 29 -------
.../apache/daffodil/runtime1/api/DFDLPrimType.java | 2 +-
.../apache/daffodil/runtime1/api/Metadata.scala | 14 ++--
.../runtime1/layers/api/ChecksumLayer.java | 26 +++---
.../apache/daffodil/runtime1/layers/api/Layer.java | 54 ++++++-------
project/Dependencies.scala | 11 ++-
7 files changed, 126 insertions(+), 102 deletions(-)
diff --git a/build.sbt b/build.sbt
index fc3b804a7..c82636cf5 100644
--- a/build.sbt
+++ b/build.sbt
@@ -75,6 +75,8 @@ lazy val io = Project("daffodil-io", file("daffodil-io"))
.settings(commonSettings, usesMacros)
lazy val runtime1 = Project("daffodil-runtime1", file("daffodil-runtime1"))
+ .enablePlugins(GenJavadocPlugin)
+ .settings(Dependencies.genjavadocVersion) // converts scaladoc to javadoc
.dependsOn(
io,
lib % "test->test",
@@ -134,6 +136,8 @@ lazy val core = Project("daffodil-core",
file("daffodil-core"))
.settings(commonSettings)
lazy val japi = Project("daffodil-japi", file("daffodil-japi"))
+ .enablePlugins(GenJavadocPlugin)
+ .settings(Dependencies.genjavadocVersion) // converts scaladoc to javadoc
.dependsOn(core, slf4jLogger % "test")
.settings(commonSettings)
@@ -246,7 +250,8 @@ lazy val commonSettings = Seq(
sourceManaged := baseDirectory.value / "src_managed",
resourceManaged := baseDirectory.value / "resource_managed",
libraryDependencies ++= Dependencies.common,
- testOptions += Tests.Argument(TestFrameworks.JUnit, "-q", "--verbosity=1")
+ testOptions += Tests.Argument(TestFrameworks.JUnit, "-q", "--verbosity=1"),
+ Compile / packageDoc / publishArtifact := false
)
def buildScalacOptions(scalaVersion: String) = {
@@ -412,30 +417,69 @@ lazy val ratSettings = Seq(
ratFailBinaries := true
)
-lazy val unidocSettings = Seq(
- ScalaUnidoc / unidoc / unidocProjectFilter := inProjects(sapi, udf),
- ScalaUnidoc / unidoc / scalacOptions := Seq(
- "-doc-title",
- "Apache Daffodil " + version.value + " Scala API",
- "-doc-root-content",
- (sapi / baseDirectory).value + "/root-doc.txt"
- ),
- JavaUnidoc / unidoc / unidocProjectFilter := inProjects(japi, udf),
- JavaUnidoc / unidoc / javacOptions := Seq(
- "-windowtitle",
- "Apache Daffodil " + version.value + " Java API",
- "-doctitle",
- "<h1>Apache Daffodil " + version.value + " Java API</h1>",
- "-notimestamp",
- "-quiet"
- ),
- JavaUnidoc / unidoc / unidocAllSources := (JavaUnidoc / unidoc /
unidocAllSources).value.map {
- sources =>
- sources.filterNot { source =>
- source.toString.contains("$") ||
source.toString.contains("packageprivate")
- }
+/**
+ * Filter to include only the doc files in our supported API classes
+ *
+ * @param sources - the sequence of files to filter
+ * @return - the filtered sequence of files
+ */
+def apiDocSourceFilter(sources: Seq[File]): Seq[File] = sources.filter {
source =>
+ val str = source.toString
+ val oad = "/org/apache/daffodil"
+ lazy val excludedForJAPI =
+ str.contains(oad + "/japi/") && {
+ // Some things are excluded from the JAPI javadoc because they are
internal, non-API
+ // These cannot be excluded from SAPI because symbols-not-found issues
with scaladoc.
+ str.contains("$") || str.contains("packageprivate")
+ }
+ lazy val included = {
+ str.contains(oad + "/udf/") ||
+ str.contains(oad + "/sapi/") ||
+ str.contains(oad + "/japi/") ||
+ str.contains(oad + "/runtime1/layers/api/")
+ //
+ // There are files in runtime1/api that are NOT part of the public,
supported API.
+ // I tried to include all of runtime1/api, and exclude those files, but
could not
+ // get that to work, so now we include individually each file that is part
of the
+ // published runtime1 API
+ //
+ // NOTE: Commented out for now. genjavadoc doesn't handle the traits in
+ // these files, so for now these are undocumented.
+ //
+ // FIXME: DAFFODIL-2902
+ // str.contains(oad + "/runtime1/api/DFDLPrimType") ||
+ // str.contains(oad + "/runtime1/api/Infoset") ||
+ // str.contains(oad + "/runtime1/api/Metadata")
}
-)
+ val res = included && !excludedForJAPI
+ res
+}
+
+lazy val unidocSettings =
+ Seq(
+ ScalaUnidoc / unidoc / unidocProjectFilter :=
+ inProjects(sapi, udf, runtime1),
+ ScalaUnidoc / unidoc / scalacOptions := Seq(
+ "-doc-title",
+ "Apache Daffodil " + version.value + " Scala API",
+ "-doc-root-content",
+ (sapi / baseDirectory).value + "/root-doc.txt"
+ ),
+ ScalaUnidoc / unidoc / unidocAllSources :=
+ (ScalaUnidoc / unidoc / unidocAllSources).value.map(apiDocSourceFilter),
+ JavaUnidoc / unidoc / unidocProjectFilter :=
+ inProjects(japi, udf, runtime1),
+ JavaUnidoc / unidoc / javacOptions := Seq(
+ "-windowtitle",
+ "Apache Daffodil " + version.value + " Java API",
+ "-doctitle",
+ "<h1>Apache Daffodil " + version.value + " Java API</h1>",
+ "-notimestamp",
+ "-quiet"
+ ),
+ JavaUnidoc / unidoc / unidocAllSources :=
+ (JavaUnidoc / unidoc / unidocAllSources).value.map(apiDocSourceFilter)
+ )
lazy val genCExamplesSettings = Seq(
Compile / genCExamples := {
diff --git a/daffodil-japi/build.sbt b/daffodil-japi/build.sbt
deleted file mode 100644
index 7207a977b..000000000
--- a/daffodil-japi/build.sbt
+++ /dev/null
@@ -1,29 +0,0 @@
-/*
- * Licensed to the Apache Software Foundation (ASF) under one or more
- * contributor license agreements. See the NOTICE file distributed with
- * this work for additional information regarding copyright ownership.
- * The ASF licenses this file to You under the Apache License, Version 2.0
- * (the "License"); you may not use this file except in compliance with
- * the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-enablePlugins(GenJavadocPlugin)
-enablePlugins(PublishJavadocPlugin)
-
-// Scala Steward may try to update this version to include the Scala version,
-// for example 0.18_2.12.15. This is incorrect because the unidoc plugin uses
-// crossVersion to figure out the Scala version. This should be set to just the
-// version of the genjavadoc plugin, without the Scala version.
-unidocGenjavadocVersion := "0.19"
-
-Genjavadoc / sources := (Genjavadoc / sources).value.filterNot { source =>
- source.toString.contains("$") || source.toString.contains("packageprivate")
-}
diff --git
a/daffodil-runtime1/src/main/scala/org/apache/daffodil/runtime1/api/DFDLPrimType.java
b/daffodil-runtime1/src/main/scala/org/apache/daffodil/runtime1/api/DFDLPrimType.java
index 64a1657d6..d44e19cd5 100644
---
a/daffodil-runtime1/src/main/scala/org/apache/daffodil/runtime1/api/DFDLPrimType.java
+++
b/daffodil-runtime1/src/main/scala/org/apache/daffodil/runtime1/api/DFDLPrimType.java
@@ -18,7 +18,7 @@ package org.apache.daffodil.runtime1.api;
/**
* An enumeration of all DFDL's simple types.
- * <p/>
+ * <p>
* Intended to be easily used from Java code calling Daffodil APIs.
*/
public enum DFDLPrimType {
diff --git
a/daffodil-runtime1/src/main/scala/org/apache/daffodil/runtime1/api/Metadata.scala
b/daffodil-runtime1/src/main/scala/org/apache/daffodil/runtime1/api/Metadata.scala
index 6686b6968..2ba8827af 100644
---
a/daffodil-runtime1/src/main/scala/org/apache/daffodil/runtime1/api/Metadata.scala
+++
b/daffodil-runtime1/src/main/scala/org/apache/daffodil/runtime1/api/Metadata.scala
@@ -33,28 +33,28 @@ trait Metadata {
* Provides the file context of a metadata component. This refers to the
specific
* DFDL schema file where the corresponding DFDL schema text resides
corresponding
* to this metadata object.
- * <p/>
+ *
* This is for use in diagnostic messaging. It is not the actual file URI,
because
* those may contain personal-identifying information about the
person/acccount and
* system that compiled the schema. It will provide enough content about the
file URI that
* a user will be able to identify which file, but some prefix of the path
* components trimmed to make it of a manageable length.
- * <p/>
- * Used along with
[[org.apache.daffodil.runtime1.api.Metadata.schemaFileLineNumber]]
- * and
[[org.apache.daffodil.runtime1.api.Metadata.schemaFileLineColumnNumber]],
+ *
+ * Used along with `schemaFileLineNumber`
+ * and `schemaFileLineColumnNumber`
* this can give a precise location in the DFDL schema file.
* @return a string containing the file information, or null if unknown.
*/
def schemaFileInfo: String
/**
- * Provides the line number to go with
[[org.apache.daffodil.runtime1.api.Metadata.schemaFileInfo]].
+ * Provides the line number to go with `schemaFileInfo`.
* @return the line number as a string, or null if unknown.
*/
def schemaFileLineNumber: JLong
/**
- * Provides the column number within the text line, to go with
[[org.apache.daffodil.runtime1.api.Metadata.schemaFileLineNumber]].
+ * Provides the column number within the text line, to go with
`schemaFileLineNumber`.
* @return the column number within the text line, as a string, or null if
unknown.
*/
def schemaFileLineColumnNumber: JLong
@@ -129,7 +129,7 @@ trait ElementMetadata extends TermMetadata {
/**
* Provides access to the runtime properties. This is an extended collection
of
* name-value pairs which are associated with a schema component.
- * <p/>
+ *
* Runtime properties are intended to use for new ad-hoc property extensions
to
* DFDL. These name-value pairs are visible to infoset outputters as well.
*
diff --git
a/daffodil-runtime1/src/main/scala/org/apache/daffodil/runtime1/layers/api/ChecksumLayer.java
b/daffodil-runtime1/src/main/scala/org/apache/daffodil/runtime1/layers/api/ChecksumLayer.java
index 35e06bec8..ed8a0feb9 100644
---
a/daffodil-runtime1/src/main/scala/org/apache/daffodil/runtime1/layers/api/ChecksumLayer.java
+++
b/daffodil-runtime1/src/main/scala/org/apache/daffodil/runtime1/layers/api/ChecksumLayer.java
@@ -23,41 +23,41 @@ import java.nio.ByteBuffer;
/**
* A checksum layer computes some sort of integer value from a region of the
data stream. The term checksum is
* used generically here to subsume all sorts of CRCs, check digits, data
hash, and digest calculations.
- * <p/>
+ * <p>
* This base is suitable only for checksums computed over small sections of
data, not large data streams or whole large
* files. The entire region of data the checksum is being computed over, will
be pulled into a byte buffer in memory.
- * <p/>
+ * <p>
* The resulting checksum is the return value of the compute method.
- * <p/>
+ * <p>
* This is delivered into a DFDL variable for use by the DFDL schema. This
variable can have any name
* such as 'crc', 'digest', or 'dataHash'.
- * <p/>
+ * <p>
* The derived implementation class must also define a getter method based on
the name of the DFDL variable which
* will be assigned with the checksum value. For example if the checksum is
actually a specific digest/hash calculation
* and the DFDL variable is named 'digest', then this getter must be defined:
- * <p/>
+ * <p>
* int getLayerVariableResult_digest() { return getChecksum() }
- * <p/>
+ * <p>
* This will be called automatically to retrieve the integer value that was
returned from the `compute` method, and
* the DFDL variable 'digest' will be assigned that value.
- * <p/>
+ * <p>
* The derived class implementing a checksum layer must call
- * <p/>
+ * <p>
* setLength(len) // sets the length in bytes
- * <p/>
+ * <p>
* to specify the length of the data region in bytes. Normally this would be
called from the layer's implementation of
* the
- * <p/>
+ * <p>
* void setLayerVariableParameters(...) { }
- * <p/>
+ * <p>
* method, which, if defined, is called with arguments populated from DFDL
variables with the same name (and compatible type)
* defined in a DFDL schema with the Layer's target namespace. So, for example
if a checksum layer needs to
* receive a parameter from a DFDL variable named "layerEncoding", the setter
would be:
- * <p/>
+ * <p>
* void setLayerVariableParameters(String layerEncoding) {
* this.layerEncoding = layerEncoding;
* }
- * <p/>
+ * <p>
* Beside initializing local members, this setter is also an initializer for
the layer class instance. Any exception
* thrown becomes a Schema Definition Error. If there are no parameter
variables, then this setter, with no arguments,
* can be used purely for initialization.
diff --git
a/daffodil-runtime1/src/main/scala/org/apache/daffodil/runtime1/layers/api/Layer.java
b/daffodil-runtime1/src/main/scala/org/apache/daffodil/runtime1/layers/api/Layer.java
index e9d244b3b..2561bdde1 100644
---
a/daffodil-runtime1/src/main/scala/org/apache/daffodil/runtime1/layers/api/Layer.java
+++
b/daffodil-runtime1/src/main/scala/org/apache/daffodil/runtime1/layers/api/Layer.java
@@ -26,52 +26,52 @@ import java.util.List;
/**
* This is the primary API class for writing layers.
- * <p/>
+ * <p>
* All layers are derived from this class, and must have no-args default
constructors.
- * <p/>
+ * <p>
* Derived classes will be dynamically loaded by Java's SPI system.
* The names of concrete classes derived from Layer are listed in a
resources/META-INF/services file
* so that they can be found and dynamically loaded.
- * <p/>
+ * <p>
* The SPI creates an instance the class by calling a default (no-arg)
constructor, which should be
* the only constructor.
- * <p/>
+ * <p>
* Instances of derived layer classes can be stateful. They are private to
threads, and each time a layer
* is encountered during parse/unparse, an instance is created for that
situation.
- * <p/>
+ * <p>
* Layer instances should not share mutable state (such as via singleton
objects)
- * <p/>
+ * <p>
* The rest of the Layer class implements the
* layer decode/encode logic, which is done as part of deriving one's Layer
class from the
* Layer base class.
- * <p/>
+ * <p>
* About variables: Layer logic may read and write DFDL variables.
- * <p/>
+ * <p>
* Every DFDL Variable in the layer's targetNamespace is used either at the
start of the
* layer algorithm as a parameter to the layer or at the end of the layer
algorithm it is
* assigned as a return value (such as a checksum) from the layer.
- * <p/>
+ * <p>
* Variables being written must be undefined, since variables in DFDL are
single-assignment.
- * <p/>
+ * <p>
* Variables being read must be defined before being read by the layer, and
this is true for both
* parsing and unparsing. When unparsing, variables being read cannot be
forward-referencing to parts
* of the DFDL infoset that have not yet been unparsed.
- * <p/>
+ * <p>
* A layer that wants to read parameters declares special setter named
'setLayerVariableParameters'
* which has args such that each has a name and type that match a corresponding
* dfdl:defineVariable in the layer's namespace.
- * <p/>
+ * <p>
* A layer that wants to return a value after the layer algorithm completes
defines a special recognizable
* getter method. The name of the getter is formed from prefixing the DFDL
variable name with the string
* 'getLayerVariableResult_'. The return type of the getter must match the
type of the variable.
- * <p/>
+ * <p>
* For example, a result value getter for a DFDL variable named 'checksum' of
type xs:unsignedShort would be:
* <pre>
* int getLayerVariableResult_checksum() {
* // returns the value created by the checksum algorithm.
* }
* </pre>
- * <p/>
+ * <p>
*/
public abstract class Layer {
@@ -97,7 +97,7 @@ public abstract class Layer {
}
/** The spiName of the Layer class.
- * <p/>
+ * <p>
* This method and the string it returns are required by the SPI loader.
* @return A unique indentifier for the kind of layer. Contains both local
and namespace components of the layer's complete name.
*/
@@ -117,10 +117,10 @@ public abstract class Layer {
/**
* Use to report a processing error.
- * <p/>
+ * <p>
* When parsing a processing error can cause backtracking so that the parse
* can often recover from the error.
- * <p/>
+ * <p>
* When unparsing a processing error is fatal.
* @param msg describes the error
*/
@@ -128,36 +128,36 @@ public abstract class Layer {
/**
* Use to report a processing error.
- * <p/>
+ * <p>
* When parsing a processing error can cause backtracking so that the parse
* can often recover from the error.
- * <p/>
+ * <p>
* When unparsing a processing error is fatal.
* @param cause a throwable object that describes the error
*/
public void processingError(Throwable cause) {
layerRuntime.processingError(cause); }
/**
* Use to report a runtime schema definition error.
- * <p/>
+ * <p>
* This indicates that the layer is unable to
* work meaningfully because of the way it is configured. The schema itself
is not well defined due to
* the way the layer is configured.
- * <p/>
+ * <p>
* This error type is always fatal whether parsing or unparsing.
- * <p/>
+ * <p>
* @param msg describes the error
*/
public void runtimeSchemaDefinitionError(String msg) {
layerRuntime.runtimeSchemaDefinitionError(msg); }
/**
* Use to report a runtime schema definition error.
- * <p/>
+ * <p>
* This indicates that the layer is unable to
* work meaningfully because of the way it is configured. The schema itself
is not well defined due to
* the way the layer is configured.
- * <p/>
+ * <p>
* This error type is always fatal whether parsing or unparsing.
- * <p/>
+ * <p>
* @param cause a throwable object that describes the error
*/
public void runtimeSchemaDefinitionError(Throwable cause) {
layerRuntime.runtimeSchemaDefinitionError(cause); }
@@ -183,12 +183,12 @@ public abstract class Layer {
/**
* Adds an exception class to the list of exceptions that will be
automatically converted
* into processing errors.
- * <p/>
+ * <p>
* The purpose of this is to allow one to use java/scala libraries that may
throw
* exceptions when encountering bad data. Such exceptions should be
translated into
* processing errors, which will allow the parser to backtrack and try other
alternatives
* which may work for that data.
- * <p/>
+ * <p>
* When considering whether a thrown Exception is to be converted to a
processing error
* RuntimeException classes are handled separately from Exception classes.
* Hence calling
diff --git a/project/Dependencies.scala b/project/Dependencies.scala
index 186a5bcd1..cdabf53d8 100644
--- a/project/Dependencies.scala
+++ b/project/Dependencies.scala
@@ -15,7 +15,8 @@
* limitations under the License.
*/
-import sbt._
+import sbt.*
+import sbtunidoc.GenJavadocPlugin.autoImport.unidocGenjavadocVersion
object Dependencies {
@@ -62,4 +63,12 @@ object Dependencies {
lazy val exi = Seq(
"com.siemens.ct.exi" % "exificient" % "1.0.7"
)
+
+ lazy val genjavadocVersion = {
+ // Scala Steward may try to update this version to include the Scala
version,
+ // for example 0.18_2.12.15. This is incorrect because the unidoc plugin
uses
+ // crossVersion to figure out the Scala version. This should be set to
just the
+ // version of the genjavadoc plugin, without the Scala version.
+ unidocGenjavadocVersion := "0.19"
+ }
}
