stevedlawrence closed pull request #113: Clean up scaladoc
URL: https://github.com/apache/incubator-daffodil/pull/113
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git
a/daffodil-japi/src/main/java/org/apache/daffodil/japi/infoset/package-info.java
b/daffodil-japi/src/main/java/org/apache/daffodil/japi/infoset/package-info.java
index 830bf5999..1cffa460d 100644
---
a/daffodil-japi/src/main/java/org/apache/daffodil/japi/infoset/package-info.java
+++
b/daffodil-japi/src/main/java/org/apache/daffodil/japi/infoset/package-info.java
@@ -18,7 +18,7 @@
/**
* Defines various classes used control the representation of the infoset for
* parse and unparse. Classes that extend {@link
org.apache.daffodil.japi.infoset.InfosetOutputter} are provided to
- * the {@link
org.apache.daffodil.japi.DataProcessor#parse(java.nio.channels.ReadableByteChannel,
org.apache.daffodil.japi.infoset.InfosetOutputter, long)} method to deteremine
how to output an infoset.
+ * the {@link
org.apache.daffodil.japi.DataProcessor#parse(org.apache.daffodil.io.InputSourceDataInputStream,
org.apache.daffodil.japi.infoset.InfosetOutputter)} method to deteremine how
to output an infoset.
* These classes are not guaranteed to be thread-safe. Classes that extend
* {@link org.apache.daffodil.japi.infoset.InfosetInputter} are provided to
the {@link
org.apache.daffodil.japi.DataProcessor#unparse(org.apache.daffodil.japi.infoset.InfosetInputter,
java.nio.channels.WritableByteChannel)} method to
* determine how to read in an infoset. A new InfosetOutputter is required for
diff --git
a/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/Daffodil.scala
b/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/Daffodil.scala
index 964ad1884..8342f7930 100644
--- a/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/Daffodil.scala
+++ b/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/Daffodil.scala
@@ -109,10 +109,10 @@ class Compiler private[sapi] () {
* Compile DFDL schema file into a [[ProcessorFactory]]
*
* To allow jar-file packaging, (where schema files might be part of a jar),
- * it is recommended to use [[Compiler#compileSource]] instead.
+ * it is recommended to use [[Compiler.compileSource]] instead.
*
* @param schemaFile DFDL schema file used to create a [[ProcessorFactory]].
- * @return [[ProcessorFactory]] used to create [[DataProcessor]](s). Must
check [[ProcessorFactory#isError]] before using it.
+ * @return [[ProcessorFactory]] used to create [[DataProcessor]](s). Must
check [[ProcessorFactory.isError]] before using it.
*/
@throws(classOf[java.io.IOException])
def compileFile(schemaFile: File): ProcessorFactory = {
@@ -125,7 +125,7 @@ class Compiler private[sapi] () {
* Compile DFDL schema source into a [[ProcessorFactory]]
*
* @param uri URI of DFDL schema file used to create a [[ProcessorFactory]].
- * @return [[ProcessorFactory]] used to create [[DataProcessor]](s). Must
check [[ProcessorFactory#isError]] before using it.
+ * @return [[ProcessorFactory]] used to create [[DataProcessor]](s). Must
check [[ProcessorFactory.isError]] before using it.
*/
@throws(classOf[java.io.IOException])
def compileSource(uri: URI): ProcessorFactory = {
@@ -138,11 +138,11 @@ class Compiler private[sapi] () {
* Reload a saved parser from a file
*
* To allow jar-file packaging, (where the savedParser might be part of a
jar),
- * it is recommended to use the other version of
[[Compiler#reload(savedParser:java\.nio\.channels\.ReadableByteChannel)*]]
where the argument is
+ * it is recommended to use the other version of
[[Compiler.reload(savedParser:java\.nio\.channels\.ReadableByteChannel)*
Compiler.reload]] where the argument is
* a java.nio.channels.ReadableByteChannel for a saved parser.
*
- * @param savedParser file of a saved parser, created with
[[DataProcessor#save]]
- * @return [[DataProcessor]] used to parse data. Must check
[[DataProcessor#isError]] before using it.
+ * @param savedParser file of a saved parser, created with
[[DataProcessor.save]]
+ * @return [[DataProcessor]] used to parse data. Must check
[[DataProcessor.isError]] before using it.
* @throws InvalidParserException if the file is not a valid saved parser.
*/
def reload(savedParser: File): DataProcessor = {
@@ -156,8 +156,8 @@ class Compiler private[sapi] () {
/**
* Reload a saved parser from a java.nio.channels.ReadableByteChannel
*
- * @param savedParser java.nio.channels.ReadableByteChannel of a saved
parser, created with [[DataProcessor#save]]
- * @return [[DataProcessor]] used to parse data. Must check
[[DataProcessor#isError]] before using it.
+ * @param savedParser java.nio.channels.ReadableByteChannel of a saved
parser, created with [[DataProcessor.save]]
+ * @return [[DataProcessor]] used to parse data. Must check
[[DataProcessor.isError]] before using it.
* @throws InvalidParserException if the file is not a valid saved parser.
*/
def reload(savedParser: ReadableByteChannel): DataProcessor = {
@@ -267,7 +267,7 @@ class ProcessorFactory private[sapi] (pf: SProcessorFactory)
* Create a [[DataProcessor]]
*
* @param path path to an element to use as the parsing root, relative to
the distinguished root node. Currently, must be set to "/"
- * @return [[DataProcessor]] used to parse data. Must check
[[DataProcessor#isError]] before using it.
+ * @return [[DataProcessor]] used to parse data. Must check
[[DataProcessor.isError]] before using it.
*/
def onPath(path: String) = {
val dp = pf.onPath(path).asInstanceOf[SDataProcessor]
@@ -280,7 +280,7 @@ class ProcessorFactory private[sapi] (pf: SProcessorFactory)
* Abstract class that adds diagnostic information to classes that extend it.
*
* When a function returns a class that extend this, one should call
- * [[WithDiagnostics#isError]] on that class before performing any further
+ * [[WithDiagnostics.isError]] on that class before performing any further
* actions. If an error exists, any use of that class, aside from those
* functions in [[WithDiagnostics]], is invalid and will result in an
* Exception.
@@ -305,7 +305,7 @@ abstract class WithDiagnostics private[sapi] (wd:
SWithDiagnostics) {
/**
* Get the list of [[Diagnostic]]'s created during the construction of the
parent object
*
- * @return list of [[Diagnostic]]'s. May contain errors or warnings, and so
may be non-empty even if [[WithDiagnostics#isError]] is false.
+ * @return list of [[Diagnostic]]'s. May contain errors or warnings, and so
may be non-empty even if [[WithDiagnostics.isError]] is false.
*/
def getDiagnostics: Seq[Diagnostic] = wd.getDiagnostics.map { new
Diagnostic(_) }
}
@@ -401,7 +401,7 @@ class DataProcessor private[sapi] (dp: SDataProcessor)
/**
* Enable/disable debugging.
*
- * Before enabling, [[DataProcessor#setDebugger]] must be called with a
non-null debugger.
+ * Before enabling, [[DataProcessor.setDebugger]] must be called with a
non-null debugger.
*
* @param flag true to enable debugging, false to disabled
*/
@@ -461,7 +461,7 @@ class DataProcessor private[sapi] (dp: SDataProcessor)
/**
* Save the DataProcessor
*
- * The resulting output can be reloaded by
[[Compiler#reload(savedParser:java\.nio\.channels\.ReadableByteChannel)*]].
+ * The resulting output can be reloaded by
[[Compiler.reload(savedParser:java\.nio\.channels\.ReadableByteChannel)*
Compiler.reload]].
* @param output the byte channel to write the [[DataProcessor]] to
*/
def save(output: WritableByteChannel): Unit = dp.save(output)
@@ -473,7 +473,7 @@ class DataProcessor private[sapi] (dp: SDataProcessor)
* @param lengthLimitInBits the length of the input data in bits, or -1 if
no limit
* @return an object which contains the result, and/or diagnostic
information.
*/
- @deprecated("Use parse(InputSourceDataInputStream, InfosetOutputter) to
parse the data and get the infoset representation from the InfosetOutputter
instead of ParseResult#result()","2.2.0")
+ @deprecated("Use parse(InputSourceDataInputStream, InfosetOutputter) to
parse the data and get the infoset representation from the InfosetOutputter
instead of ParseResult.result()","2.2.0")
def parse(input: ReadableByteChannel, lengthLimitInBits: Long): ParseResult
= {
val is = Channels.newInputStream(input)
val dis = new InputSourceDataInputStream(is)
@@ -491,7 +491,7 @@ class DataProcessor private[sapi] (dp: SDataProcessor)
* @param input data to be parsed
* @return an object which contains the result, and/or diagnostic
information.
*/
- @deprecated("Use parse(InputSourceDataInputStream, InfosetOutputter) to
parse the data and get the infoset representation from the InfosetOutputter
instead of ParseResult#result()","2.2.0")
+ @deprecated("Use parse(InputSourceDataInputStream, InfosetOutputter) to
parse the data and get the infoset representation from the InfosetOutputter
instead of ParseResult.result()","2.2.0")
def parse(input: ReadableByteChannel): ParseResult = parse(input, -1)
/**
@@ -502,7 +502,7 @@ class DataProcessor private[sapi] (dp: SDataProcessor)
* @param lengthLimitInBits the length of the input data in bits, or -1 if
no limit
* @return an object which contains the result, and/or diagnostic
information.
*/
- @deprecated("Use parse(InputSourceDataInputStream, InfosetOutputter) to
parse the data and get the infoset representation from the InfosetOutputter
instead of ParseResult#result()","2.2.0")
+ @deprecated("Use parse(InputSourceDataInputStream, InfosetOutputter) to
parse the data and get the infoset representation from the InfosetOutputter
instead of ParseResult.result()","2.2.0")
def parse(input: ReadableByteChannel, output: InfosetOutputter,
lengthLimitInBits: Long): ParseResult = {
val is = Channels.newInputStream(input)
val dis = new InputSourceDataInputStream(is)
@@ -522,7 +522,7 @@ class DataProcessor private[sapi] (dp: SDataProcessor)
* @param output the InfosetOutputter that will be used to output the infoset
* @return an object which contains the result, and/or diagnostic
information.
*/
- @deprecated("Use parse(InputSourceDataInputStream, InfosetOutputter) to
parse the data and get the infoset representation from the InfosetOutputter
instead of ParseResult#result()","2.2.0")
+ @deprecated("Use parse(InputSourceDataInputStream, InfosetOutputter) to
parse the data and get the infoset representation from the InfosetOutputter
instead of ParseResult.result()","2.2.0")
def parse(input: ReadableByteChannel, output: InfosetOutputter): ParseResult
= parse(input, output, -1)
/**
@@ -565,7 +565,7 @@ class DataProcessor private[sapi] (dp: SDataProcessor)
}
/**
- * Result of calling
[[DataProcessor#parse(input:java\.nio\.channels\.ReadableByteChannel,output:org\.apache\.daffodil\.sapi\.infoset\.InfosetOutputter)*]],
containing
+ * Result of calling [[DataProcessor.parse(input:org\.apache\.daffodil*
DataProcessor.parse]], containing
* any diagnostic information, and the final data location
*/
class ParseResult private[sapi] (pr: SParseResult, deprecatedOutput:
Maybe[ScalaXMLInfosetOutputter])
@@ -620,7 +620,7 @@ class ParseResult private[sapi] (pr: SParseResult,
deprecatedOutput: Maybe[Scala
}
/**
- * Result of calling [[DataProcessor#unparse(input*]],
+ * Result of calling [[DataProcessor.unparse(input* DataProcessor.unparse]],
* containing diagnostic information
*/
class UnparseResult private[sapi] (ur: SUnparseResult)
diff --git
a/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/infoset/Infoset.scala
b/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/infoset/Infoset.scala
index fd91ba207..126e59b60 100644
---
a/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/infoset/Infoset.scala
+++
b/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/infoset/Infoset.scala
@@ -41,7 +41,7 @@ import org.apache.daffodil.dpath.NodeInfo
/**
* Abstract class used to determine how the infoset representation should be
- * input from a call to [[DataProcessor#unparse(input*]]. This uses a Cursor
API, such
+ * input from a call to [[DataProcessor.unparse(input*
DataProcessor.unparse]]. This uses a Cursor API, such
* that each call to advance/inspect must update a cursor value, minimizing
* allocations. Callers of advance/inspect are expected to copy out any
* information from advanceAccessor and inspectAccessor if they need to retain
@@ -98,7 +98,7 @@ abstract class InfosetInputter extends SInfosetInputter {
/**
* Abstract class used to determine how the infoset representation should be
- * output from a call to
[[DataProcessor#parse(input:java\.nio\.channels\.ReadableByteChannel,output:org\.apache\.daffodil\.sapi\.infoset\.InfosetOutputter)*]].
The Daffodil core will call
+ * output from a call to [[DataProcessor.parse(input:org\.apache\.daffodil*
DataProcessor.parse]]. The Daffodil core will call
* the various methods of this class in an order appropriate to create an
* infoset representation.
*
diff --git
a/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/infoset/package.scala
b/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/infoset/package.scala
index 405c79032..85fd6adf6 100644
---
a/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/infoset/package.scala
+++
b/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/infoset/package.scala
@@ -19,10 +19,10 @@ package org.apache.daffodil.sapi
/**
* Defines various classes used control the representation of the infoset for
parse and unparse.
- * Classes that extend [[InfosetOutputter]] are provided to the
[[DataProcessor#parse(input:java\.nio\.channels\.ReadableByteChannel,output:org\.apache\.daffodil\.sapi\.infoset\.InfosetOutputter)*]]
+ * Classes that extend [[InfosetOutputter]] are provided to the
[[DataProcessor.parse(input:org\.apache\.daffodil* DataProcessor.parse]]
* method to deteremine how to output an infoset. These classes are not
* guaranteed to be thread-safe. Classes that extend [[InfosetInputter]] are
- * provided to the [[DataProcessor#unparse(input*]] method to determine how to
read in
+ * provided to the [[DataProcessor.unparse(input* DataProcessor.unparse]]
method to determine how to read in
* an infoset. A new InfosetOutputter is required for each call to unparse().
*/
diff --git
a/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/logger/Logger.scala
b/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/logger/Logger.scala
index b4ca52f21..a53edec94 100644
--- a/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/logger/Logger.scala
+++ b/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/logger/Logger.scala
@@ -79,7 +79,7 @@ abstract class LogWriter {
*
* The default implementation generates a log message based on the prefix,
* suffix, message string, and log arguments, and passes the generated log
- * message, level, and logId to [[LogWriter#write]].
+ * message, level, and logId to [[LogWriter.write]].
*
* Can be overridden if more control is needed over the logging mechanism
and/or
* log arguments are needed as separate entities.
diff --git
a/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/logger/package.scala
b/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/logger/package.scala
index 9fce288fa..681ef25a5 100644
--- a/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/logger/package.scala
+++ b/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/logger/package.scala
@@ -38,8 +38,8 @@ package org.apache.daffodil.sapi
* }}}
*
* One may also change the log level using [[Daffodil.setLoggingLevel]], which
- * defaults to [[LogLevel#Info]] if not set. For example, to change the log
- * level to [[LogLevel#Warning]]:
+ * defaults to [[LogLevel.Info]] if not set. For example, to change the log
+ * level to [[LogLevel.Warning]]:
* {{{
* Daffodil.setLoggingLevel(LogLevel.Warning);
* }}}
diff --git
a/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/package.scala
b/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/package.scala
index 6b0a8973e..47e1b2007 100644
--- a/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/package.scala
+++ b/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/package.scala
@@ -41,8 +41,8 @@ package org.apache.daffodil
*
* <h4>Parse</h4>
*
- * The
[[DataProcessor#parse(input:org\.apache\.daffodil\.sapi\.io\.InputSourceDataInputStream,output:org\.apache\.daffodil\.sapi\.infoset\.InfosetOutputter)*]]
method accepts input data to parse in the form
- * of a [[io.InputSourceDataInputStream]] and an [[infoset.InfosetOutputter]]
+ * The
[[DataProcessor.parse(input:org\.apache\.daffodil\.sapi\.io\.InputSourceDataInputStream*
DataProcessor.parse]] method accepts input data to parse in the form
+ * of a [[io.InputSourceDataInputStream InputSourceDataInputStream]] and an
[[infoset.InfosetOutputter InfosetOutputter]]
* to determine the output representation of the infoset (e.g. Scala XML Nodes,
* JDOM2 Documents, etc.):
*
@@ -53,10 +53,10 @@ package org.apache.daffodil
* val node = scalaOutputter.getResult
* }}}
*
- * The
[[DataProcessor#parse(input:org\.apache\.daffodil\.sapi\.io\.InputSourceDataInputStream,output:org\.apache\.daffodil\.sapi\.infoset\.InfosetOutputter)*]]
method is thread-safe and may be called multiple
+ * The
[[DataProcessor.parse(input:org\.apache\.daffodil\.sapi\.io\.InputSourceDataInputStream*
DataProcessor.parse]] method is thread-safe and may be called multiple
* times without the need to create other data processors. However,
- * [[infoset.InfosetOutputter]]'s are not thread safe, requiring a unique
instance per
- * thread. An [[infoset.InfosetOutputter]] should call
[[infoset.InfosetOutputter#reset]] before
+ * [[infoset.InfosetOutputter InfosetOutputter]]'s are not thread safe,
requiring a unique instance per
+ * thread. An [[infoset.InfosetOutputter InfosetOutputter]] should call
[[infoset.InfosetOutputter.reset InfosetOutputter.reset]] before
* reuse (or a new one should be allocated). For example:
*
* {{{
@@ -66,7 +66,7 @@ package org.apache.daffodil
* val is = new InputSourceDataInputStream(new FileInputStream(f))
* val pr = dp.parse(is, scalaOutputter)
* val node = scalaOutputter.getResult
- * }}
+ * }
* }}}
*
* One can repeat calls to parse() using the same InputSourceDataInputStream
to continue parsing where the previous parse ended. For example:
@@ -80,12 +80,13 @@ package org.apache.daffodil
* val pr = dp.parse(is, jdomOutputter)
* ...
* keepParsing = !pr.location().isAtEnd() && !pr.isError()
+ * }
* }}}
*
* <h4>Unparse</h4>
*
* The same [[DataProcessor]] used for parse can be used to unparse an infoset
- * via the [[DataProcessor#unparse(input*]] method. An
[[infoset.InfosetInputter]]
+ * via the [[DataProcessor.unparse(input* DataProcessor.unparse]] method. An
[[infoset.InfosetInputter InfosetInputter]]
* provides the infoset to unparse, with the unparsed data written to the
* provided java.nio.channels.WritableByteChannel. For example:
*
@@ -102,7 +103,7 @@ package org.apache.daffodil
* error, etc), these classes extend [[WithDiagnostics]], which is used to
* determine if an error occurred, and any diagnostic information (see
* [[Diagnostic]]) related to the step. Thus, before continuing, one must check
- * [[WithDiagnostics#isError]]. For example:
+ * [[WithDiagnostics.isError]]. For example:
*
* {{{
* val pf = c.compile(file)
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
With regards,
Apache Git Services
