From 799f61d7c8f57b248be5bfef3520566266952298 Mon Sep 17 00:00:00 2001 From: Miroslav Blasko Date: Sat, 30 Sep 2023 22:38:57 +0200 Subject: [PATCH] [#218] Improve documentation of parameters --- .../modules/GetDatasetDescriptorsModule.java | 6 ++++-- .../modules/FetchPossibleValuesModule.java | 4 +++- .../spipes/modules/MergeFormMetadataModule.java | 9 +++++---- .../cvut/spipes/modules/Rdf4jUpdateModule.java | 17 +++++++++++++---- .../modules/ApplyConstructAbstractModule.java | 8 ++++++-- .../cz/cvut/spipes/modules/TabularModule.java | 7 +++++-- .../modules/ExtractTermOccurrencesModule.java | 4 +++- 7 files changed, 39 insertions(+), 16 deletions(-) diff --git a/s-pipes-modules/module-dataset-discovery/src/main/java/cz/cvut/spipes/modules/GetDatasetDescriptorsModule.java b/s-pipes-modules/module-dataset-discovery/src/main/java/cz/cvut/spipes/modules/GetDatasetDescriptorsModule.java index 691df6a2..7233e922 100644 --- a/s-pipes-modules/module-dataset-discovery/src/main/java/cz/cvut/spipes/modules/GetDatasetDescriptorsModule.java +++ b/s-pipes-modules/module-dataset-discovery/src/main/java/cz/cvut/spipes/modules/GetDatasetDescriptorsModule.java @@ -18,7 +18,8 @@ import java.util.Collections; import java.util.Optional; -@SPipesModule(label = "get dataset descriptors v1", comment = "Retrieve dataset descriptor for dataset with dataset-iri in endpoint-url.") +@SPipesModule(label = "get dataset descriptors v1", comment = "Retrieve dataset descriptor for dataset" + + " with dataset-iri in endpoint-url.") public class GetDatasetDescriptorsModule extends AbstractModule { private static final Logger LOG = LoggerFactory.getLogger(GetDatasetDescriptorsModule.class); @@ -35,7 +36,8 @@ public class GetDatasetDescriptorsModule extends AbstractModule { @Parameter(urlPrefix = PARAM_URI, name = "p-dataset-iri", comment = "IRI of the dataset.")// TODO - revise comment private String prpDatasetIri; - @Parameter(urlPrefix = PARAM_URI, name = "endpoint-url", comment = "URL of the SPARQL endpoint. Default value is 'http://onto.fel.cvut.cz/rdf4j-server/repositories/descriptors-metadata'") + @Parameter(urlPrefix = PARAM_URI, name = "endpoint-url", comment = "URL of the SPARQL endpoint. Default value" + + " is 'http://onto.fel.cvut.cz/rdf4j-server/repositories/descriptors-metadata'") private String endpointUrl = "http://onto.fel.cvut.cz/rdf4j-server/repositories/descriptors-metadata"; private static Property getParameter(final String name) { diff --git a/s-pipes-modules/module-form/src/main/java/cz/cvut/spipes/modules/FetchPossibleValuesModule.java b/s-pipes-modules/module-form/src/main/java/cz/cvut/spipes/modules/FetchPossibleValuesModule.java index e85f2e6f..c88501e1 100644 --- a/s-pipes-modules/module-form/src/main/java/cz/cvut/spipes/modules/FetchPossibleValuesModule.java +++ b/s-pipes-modules/module-form/src/main/java/cz/cvut/spipes/modules/FetchPossibleValuesModule.java @@ -25,7 +25,9 @@ public class FetchPossibleValuesModule extends AnnotatedAbstractModule { private static final Logger LOG = LoggerFactory.getLogger(FetchPossibleValuesModule.class); private static final String TYPE_URI = KBSS_MODULE.uri + "fetch-possible-values"; - @Parameter(urlPrefix = SML.uri, name = "replace", comment = "Replace context flag, default is false.") //TODO - revise comment + @Parameter(urlPrefix = SML.uri, name = "replace", comment = "Specifies whether a module should overwrite triples" + + " from its predecessors. When set to true (default is false), it prevents" + + " passing through triples from the predecessors.") private boolean isReplace = false; diff --git a/s-pipes-modules/module-form/src/main/java/cz/cvut/spipes/modules/MergeFormMetadataModule.java b/s-pipes-modules/module-form/src/main/java/cz/cvut/spipes/modules/MergeFormMetadataModule.java index 18bc50e0..c70b3b07 100644 --- a/s-pipes-modules/module-form/src/main/java/cz/cvut/spipes/modules/MergeFormMetadataModule.java +++ b/s-pipes-modules/module-form/src/main/java/cz/cvut/spipes/modules/MergeFormMetadataModule.java @@ -18,8 +18,8 @@ @SPipesModule(label = "merge form metadata", comment = "Merges form metadata. Inputs are sample form and Q&A model. Questions from both models are remapped to new" + - "IRIs based on question origin combined with executionId. New question instances are created using" + - "questionInstanceTemplate which defaults to \"doc:question-{_questionOriginHash}-{_executionId}\"." + " IRIs based on question origin combined with executionId. New question instances are created using" + + " question-instance-template property which defaults to \"doc:question-{_questionOriginHash}-{_executionId}\"." ) public class MergeFormMetadataModule extends AnnotatedAbstractModule { @@ -31,13 +31,14 @@ public class MergeFormMetadataModule extends AnnotatedAbstractModule { private static final String QUESTION_ORIGIN_HASH_VAR = "{_questionOriginHash}"; private static final String EXECUTION_ID_VAR = "{_executionId}"; - @Parameter(urlPrefix = SML.uri, name = "replace", comment = "Replace context flag. Default value is false.") // TODO - revise comment + @Parameter(urlPrefix = SML.uri, name = "replace", comment = "Specifies whether a module should overwrite triples" + + " from its predecessors. When set to true (default is false), it prevents" + + " passing through triples from the predecessors.") private boolean isReplace = false; @Parameter(name = "execution-id", comment = "Execution id that will be used to construct question IRIs") private String executionId = DigestUtils.md5Hex(Long.toString(RANDOM.nextLong())); - // TODO - revise comment @Parameter(name = "question-instance-template", comment = "URL Template to create URL for question instances. " + "Default is 'http://onto.fel.cvut.cz/ontologies/documentation/question-{_questionOriginHash}-{_executionId}'") private String questionInstanceTemplate = diff --git a/s-pipes-modules/module-rdf4j/src/main/java/cz/cvut/spipes/modules/Rdf4jUpdateModule.java b/s-pipes-modules/module-rdf4j/src/main/java/cz/cvut/spipes/modules/Rdf4jUpdateModule.java index bc039f6f..141d0954 100644 --- a/s-pipes-modules/module-rdf4j/src/main/java/cz/cvut/spipes/modules/Rdf4jUpdateModule.java +++ b/s-pipes-modules/module-rdf4j/src/main/java/cz/cvut/spipes/modules/Rdf4jUpdateModule.java @@ -27,7 +27,9 @@ import java.util.List; import java.util.stream.Collectors; -@SPipesModule(label = "rdf4j update", comment = "Updates sparql endpoint configured in rdf4jServerURL using specified updateQueries.") +@SPipesModule(label = "rdf4j update", comment = "Updates sparql endpoint configured in rdf4jServerURL" + + " using specified list updateQueries. The list of queries can be executed multiple times specified by " + + " `has-max-iteration-count` property.") public class Rdf4jUpdateModule extends AbstractModule { private static final Logger LOG = LoggerFactory.getLogger(Rdf4jUpdateModule.class.getName()); private static final String TYPE_URI = KBSS_MODULE.uri + "rdf4j-update"; @@ -42,18 +44,25 @@ public class Rdf4jUpdateModule extends AbstractModule { @Parameter(urlPrefix = PROPERTY_PREFIX_URI + "/", name = "p-rdf4j-repository-name", comment = "Rdf4j repository ID") private String rdf4jRepositoryName; - @Parameter(urlPrefix = SML.uri, name = "updateQuery", comment = "A list of SPARQL Update queries. Queries strings are read from sp:text.")// TODO - revise comment + /** + * List of SPARQL Update queries that will be executed in this order. + */ + @Parameter(urlPrefix = SML.uri, name = "updateQuery", comment = "SPARQL Update query (sp:Update) that should" + + " be executed by this module. The query is read from sp:text property.") private List updateQueries; static final Property P_RDF4J_STOP_ITERATION_ON_STABLE_TRIPLE_COUNT = getParameter("p-stop-iteration-on-stable-triple-count"); @Parameter(urlPrefix = PROPERTY_PREFIX_URI + "/", name = "p-stop-iteration-on-stable-triple-count", - comment = "Stops iteration on if triple count did not change. Default is false.") // TODO - revise comment + comment = "Stops iteration (i.e. execution of list of queries) if triple count " + + "in the last iteration did not change. Default is false.") private boolean onlyIfTripleCountChanges; @Parameter(urlPrefix = PROPERTY_PREFIX_URI + "/", name = "has-max-iteration-count", - comment = "Limits the number of iterations to the specified value. Default value is 1.") // TODO - revise comment + comment = "Limits the number of iterations (i.e. executions of list of queries)" + + " to the specified value. Default value is 1, which means that all" + + " update queries are executed only once.") private int iterationCount; private Repository updateRepository; diff --git a/s-pipes-modules/module-sparql-endpoint/src/main/java/cz/cvut/spipes/modules/ApplyConstructAbstractModule.java b/s-pipes-modules/module-sparql-endpoint/src/main/java/cz/cvut/spipes/modules/ApplyConstructAbstractModule.java index d78227fd..291fa30e 100644 --- a/s-pipes-modules/module-sparql-endpoint/src/main/java/cz/cvut/spipes/modules/ApplyConstructAbstractModule.java +++ b/s-pipes-modules/module-sparql-endpoint/src/main/java/cz/cvut/spipes/modules/ApplyConstructAbstractModule.java @@ -27,11 +27,15 @@ public abstract class ApplyConstructAbstractModule extends AnnotatedAbstractModu private static final String PROPERTY_PREFIX_URI = KBSS_MODULE.uri + ""; //sml:constructQuery // TODO - this parameter is reused in ApplyConstructWithChunkedValuesAndScrollableCursorModule. There the comment should be extended by a note, i.e. "The construct queries with markers #${VALUES} and #${LIMIT_OFFSET}." - @Parameter(urlPrefix = SML.uri, name = "constructQuery", comment = "List of construct queries the output of which is returned by the module.") //TODO - revise comment + @Parameter(urlPrefix = SML.uri, name = "constructQuery", comment = "SPARQL Construct query (sp:Construct)" + + " that should be executed by this module. The query is read from sp:text property." + + " The output of query execution is returned by the module.") protected List constructQueries; //sml:replace - @Parameter(urlPrefix = SML.uri, name = "replace", comment = "Replace context flag, default is false.") + @Parameter(urlPrefix = SML.uri, name = "replace", comment = "Specifies whether a module should overwrite triples" + + " from its predecessors. When set to true (default is false), it prevents" + + " passing through triples from the predecessors.") protected boolean isReplace; //kbss:parseText diff --git a/s-pipes-modules/module-tabular/src/main/java/cz/cvut/spipes/modules/TabularModule.java b/s-pipes-modules/module-tabular/src/main/java/cz/cvut/spipes/modules/TabularModule.java index 6cb1a4f4..688fecee 100644 --- a/s-pipes-modules/module-tabular/src/main/java/cz/cvut/spipes/modules/TabularModule.java +++ b/s-pipes-modules/module-tabular/src/main/java/cz/cvut/spipes/modules/TabularModule.java @@ -114,10 +114,13 @@ public class TabularModule extends AbstractModule { private final Property P_PROCESS_SPECIFIC_SHEET_IN_XLS_FILE = getSpecificParameter("process-specific-sheet-in-xls-file"); //sml:replace - @Parameter(urlPrefix = SML.uri, name = "replace", comment = "Replace context flag. Default is false.")// TODO - revise comment + @Parameter(urlPrefix = SML.uri, name = "replace", comment = "Specifies whether a module should overwrite triples" + + " from its predecessors. When set to true (default is false), it prevents" + + " passing through triples from the predecessors.") private boolean isReplace; - @Parameter(urlPrefix = PARAM_URL_PREFIX, name = "source-resource-uri", comment = "Resource URI of the source table.") // TODO - revise comment + @Parameter(urlPrefix = PARAM_URL_PREFIX, name = "source-resource-uri", comment = "URI of resource" + + " that represent tabular data (e.g. resource representing CSV file).") //:source-resource-uri private StreamResource sourceResource; diff --git a/s-pipes-modules/module-text-analysis/src/main/java/cz/cvut/spipes/modules/ExtractTermOccurrencesModule.java b/s-pipes-modules/module-text-analysis/src/main/java/cz/cvut/spipes/modules/ExtractTermOccurrencesModule.java index ce7a3e10..abe13e01 100644 --- a/s-pipes-modules/module-text-analysis/src/main/java/cz/cvut/spipes/modules/ExtractTermOccurrencesModule.java +++ b/s-pipes-modules/module-text-analysis/src/main/java/cz/cvut/spipes/modules/ExtractTermOccurrencesModule.java @@ -77,7 +77,9 @@ public class ExtractTermOccurrencesModule extends AnnotatedAbstractModule { private static final String TYPE_URI = KBSS_MODULE.uri + "extract-term-occurrences"; private static final String TYPE_PREFIX = TYPE_URI + "/"; - @Parameter(urlPrefix = SML.uri, name = "replace", comment = "Indicates whether the existing RDF should be overwritten. Default false.") // TODO - revise comment + @Parameter(urlPrefix = SML.uri, name = "replace", comment = "Specifies whether a module should overwrite triples" + + " from its predecessors. When set to true (default is false), it prevents" + + " passing through triples from the predecessors.") private boolean isReplace; Extraction extraction = new Extraction();