Doc fixes (#4229)

* fixes for doxygen doc batch_file.h

* fixes for doxygen doc batch_queue.h

* fixes for doxygen doc jx_parse.h

* fixes for doxygen doc jx_parse.h

* fixes for doxygen doc link.h

* fixes for doxygen doc manager.py

* fixes for doxygen doc task.py

* fixes for doxygen doc taskvine.h

Author: btovar

batch_job/src/batch_file.h

@@ -42,7 +42,7 @@ struct batch_file *batch_file_create(const char *outer_name, const char *inner_n
 This includes freeing host_name and exe_name if defined.
 @param file A batch_file struct to be deleted.
 */
-void batch_file_delete(struct batch_file *f);
+void batch_file_delete( struct batch_file *file );
 
 /** Output batch_file as a string.
 * Format is "outer_name=inner_name" when renaming is needed.
@@ -51,21 +51,21 @@ void batch_file_delete(struct batch_file *f);
 * @return pointer to char * representing the flattened list.
 */
 
-char * batch_file_to_string( struct batch_file *f );
+char * batch_file_to_string( struct batch_file *file );
 
 /** Output list of batch_files as a string.
 * Format is "FILE,FILE,...,FILE" where file is the result of batch_file_to_string.
 * @param files A list struct containing batch_file structs. 
 * @return pointer to char * representing the flattened list.
 */
-char * batch_file_list_to_string( struct list *file_list );
+char * batch_file_list_to_string( struct list *files );
 
 /** Compare function for comparing batch_files based on outer_name.
 @param file1 First file to compare.
 @param file2 Second file to compare.
 @return Relative alphabetic order of files outer_name's
 */
-int batch_file_outer_compare( struct batch_file *f1, struct batch_file *f2 );
+int batch_file_outer_compare( struct batch_file *file1, struct batch_file *file2 );
 
 /** Generate a sha1 hash based on the file contents.
 @param f The batch_file whose checksum will be generated.

batch_job/src/batch_queue.h

@@ -87,15 +87,14 @@ typedef enum {
 /** Create a new batch queue.
 @param type The type of the queue.
 @param ssl_key_file The location of the queue manager's ssl key file, if it has one.
-@param ssl_key_file The location of the queue manager's ssl certiciate file, if it has one.
+@param ssl_cert_file The location of the queue manager's ssl certiciate file, if it has one.
 @return A new batch queue object on success, null on failure.
 */
 struct batch_queue *batch_queue_create(batch_queue_type_t type, const char *ssl_key_file, const char *ssl_cert_file );
 
 /** Submit a batch job.
 @param q The queue to submit to.
 @param task The job description to submit.
-@param resources The computational resources needed by the job.
 @return On success, returns a positive unique identifier for the batch job.  On failure, returns a negative number.
 Zero is not a valid batch job id and indicates an internal failure.
 */

batch_job/src/batch_wrapper.h

@@ -34,6 +34,7 @@ See: Nick Hazekamp, "An Algebra for Robust Workflow Transformations", eScience 2
 struct batch_wrapper *batch_wrapper_create(void);
 
 /** Free a batch_wrapper.
+ * @param w A wrapper structure from @ref batch_wrapper_create.
  * Any scripts written out will continue to work after
  * calling this function.
  */
@@ -43,6 +44,7 @@ void batch_wrapper_delete(struct batch_wrapper *w);
  * Can be called multiple times to append multiple commands.
  * These commands run before the main wrapper command.
  * Each command must be a self-contained shell statement.
+ * @param w A wrapper structure from @ref batch_wrapper_create.
  * @param cmd The shell command to add.
  */
 void batch_wrapper_pre(struct batch_wrapper *w, const char *cmd);
@@ -51,19 +53,22 @@ void batch_wrapper_pre(struct batch_wrapper *w, const char *cmd);
  * The arguments in argv are executed as-is, with no shell interpretation.
  * This command executes after any pre commands.
  * It is undefined behavior to add another command after calling this.
+ * @param w A wrapper structure from @ref batch_wrapper_create.
  * @param argv The command line to run.
  */
 void batch_wrapper_argv(struct batch_wrapper *w, char *const argv[]);
 
 /** Specify a command line to execute with shell interpretation.
  * Same as batch_wrapper_argv, but each arg is individually
  * interpreted by the shell for variable substitution and such.
+ * @param w A wrapper structure from @ref batch_wrapper_create.
  * @param args The command line to run.
  */
 void batch_wrapper_args(struct batch_wrapper *w, char *const args[]);
 
 /** Specify a shell command to execute.
  * Same as batch_wrapper_argv, but takes a shell command.
+ * @param w A wrapper structure from @ref batch_wrapper_create.
  * @param cmd The command line to run.
  */
 void batch_wrapper_cmd(struct batch_wrapper *w, const char *cmd);
@@ -73,6 +78,7 @@ void batch_wrapper_cmd(struct batch_wrapper *w, const char *cmd);
  * The shell statement specified will be executed before exiting the wrapper,
  * even if previous commands failed. This is a good place for cleanup actions.
  * Can be called multiple times.
+ * @param w A wrapper structure from @ref batch_wrapper_create.
  * @param cmd The shell command to add.
  */
 void batch_wrapper_post(struct batch_wrapper *w, const char *cmd);
@@ -81,14 +87,15 @@ void batch_wrapper_post(struct batch_wrapper *w, const char *cmd);
  * The actual filename will consist of the prefix, an underscore,
  * and some random characters to ensure that the name is unique.
  * Defaults to "./wrapper"
+ * @param w A wrapper structure from @ref batch_wrapper_create.
  * @param prefix The filename prefix to use.
  */
 void batch_wrapper_prefix(struct batch_wrapper *w, const char *prefix);
 
 /**
  * Write out the batch_wrapper as a shell script.
  * Does not consume the batch_wrapper.
- * @param prefix The prefix to use to generate a unique name for the wrapper.
+ * @param w A wrapper structure from @ref batch_wrapper_create.
  * @returns The name of the generated wrapper, which the caller must free().
  * @returns NULL on failure, and sets errno.
  */
@@ -97,6 +104,8 @@ char *batch_wrapper_write(struct batch_wrapper *w, struct batch_job *t);
 /** Generate one or more wrapper scripts from a JX command spec.
  * All generated scripts will be added as inputs to the given
  * batch task.
+ * @param t A batch_job structure.
+ * @param spec A command description.
  * @returns The name of the outermost wrapper script.
  * @returns NULL on failure, and sets errno.
  */

dttools/src/jx_parse.h

@@ -31,7 +31,7 @@ void jx_parse_set_static_mode( bool mode );
 /** Parse a JSON string to a JX expression.  @param str A null-terminated C string containing JSON data.  @return A JX expression which must be deleted with @ref jx_delete. If the parse fails or no JSON value is present, null is returned. */
 struct jx * jx_parse_string( const char *str );
 
-/** Parse a JSON string to a JX expression.  @param str An unterminated string containing JSON data.  @param Length of the string in bytes.  @return A JX expression which must be deleted with @ref jx_delete. If the parse fails or no JSON value is present, null is returned. */
+/** Parse a JSON string to a JX expression.  @param str An unterminated string containing JSON data.  @param length of the string in bytes.  @return A JX expression which must be deleted with @ref jx_delete. If the parse fails or no JSON value is present, null is returned. */
 struct jx * jx_parse_string_and_length( const char *str, int length );
 
 /** Parse a standard IO stream to a JX expression.  @param file A stream containing JSON data.  @return A JX expression which must be deleted with @ref jx_delete. If the parse fails or no JSON value is present, null is returned. */

dttools/src/link.h

@@ -115,6 +115,7 @@ struct link *link_serve_address(const char *addr, int port);
 
 /** Prepare to accept connections on one network interface.
 Functions like @ref link_serve, except that the server will only be visible on the given network interface.
+@param addr IP address of the network interface.
 @param low The low port in a range to listen on (inclusive).
 @param high The high port in a range to listen on (inclusive).
 @return link A server endpoint that can be passed to @ref link_accept, or null on failure.

taskvine/src/bindings/python3/ndcctools/taskvine/manager.py

@@ -392,6 +392,7 @@ def set_category_autolabel_resource(self, category, resource, autolabel):
 
     ##
     # Get current task state. See @ref vine_task_state_t for possible values.
+    # @param task_id  The task_id returned from @ref ndcctools.taskvine.manager.Manager.submit.
     # @code
     # >>> print(q.task_state(task_id))
     # @endcode
@@ -559,7 +560,7 @@ def set_catalog_servers(self, catalogs):
     # This is helpful for distinguishing higher level information about the entire run,
     # such as the name of the framework being used, or the logical name of the dataset
     # being processed.
-    # @param m A manager object
+    # @param self Reference to the current manager object.
     # @param name The name of the property.
     # @param value The value of the property.
     def set_property(self, name, value):
@@ -1756,16 +1757,16 @@ def declare_chirp(self, server, source, ticket=None, env=None, cache=False, peer
     ##
     # Adds a custom APPLICATION entry to the transactions log.
     #
-    # @param self   The manager to register this file.
-    # @param server A custom transaction message
+    # @param self The manager to register this file.
+    # @param entry A custom transaction message
     def log_txn_app(self, entry):
         cvine.vine_log_txn_app(self._taskvine, entry)
 
     ##
     # Adds a custom APPLICATION entry to the debug log.
     #
     # @param self   The manager to register this file.
-    # @param server A custom debug message
+    # @param entry A custom debug message
     def log_debug_app(self, entry):
         cvine.vine_log_debug_app(self._taskvine, entry)
 

taskvine/src/bindings/python3/ndcctools/taskvine/task.py

@@ -339,6 +339,7 @@ def add_feature(self, name):
     # @param self          Reference to the current task object.
     # @param file          A file object of class @ref ndcctools.taskvine.file.File, such as from @ref ndcctools.taskvine.manager.Manager.declare_file, @ref ndcctools.taskvine.manager.Manager.declare_buffer, @ref ndcctools.taskvine.manager.Manager.declare_url, etc.
     # @param remote_name   The name of the file at the execution site.
+    # @param mount_symlink Whether to mount file in task's sandbox as a symlink. The default (False) mounts it as a hard link.
     # @param strict_input  Whether the file should be transfered to the worker
     #                      for execution. If no worker has all the input files already cached marked
     #                      as strict inputs for the task, the task fails.
@@ -450,8 +451,8 @@ def set_snapshot_file(self, filename):
     # The file given must refer to a (unpacked) package
     # containing libraries captured by the <tt>starch</tt> command.
     # The task will execute using this package as its environment.
-    # @param t A task object.
-    # @param f A file containing an unpacked Starch package.
+    # @param self The current task object.
+    # @param file A file containing an unpacked Starch package.
     def add_starch_package(self, file):
         return cvine.vine_task_add_starch_package(self._task, file._file)
 
@@ -460,8 +461,8 @@ def add_starch_package(self, file):
     # The file given must refer to a (unpacked) PONCHO package,
     # containing a set of Python modules needed by the task.
     # The task will execute using this package as its Python environment.
-    # @param t A task object.
-    # @param f A file containing an unpacked Poncho package.
+    # @param self The current task object.
+    # @param file A file containing an unpacked Poncho package.
     def add_poncho_package(self, file):
         return cvine.vine_task_add_poncho_package(self._task, file._file)
 
@@ -477,7 +478,7 @@ def add_poncho_package(self, file):
     # nested in the order given (i.e. first added is the first applied).
     # @see add_poncho_package
     # @see add_starch_package
-    # @param t A task object.
+    # @param self The current task object.
     # @param f The execution context file.
     def add_execution_context(self, f):
         return cvine.vine_task_add_execution_context(self._task, f._file)
@@ -899,7 +900,6 @@ def __init__(self, func, *args, **kwargs):
     # execution.
     #
     # @param self 	Reference to the current python task object
-    # @param manager Manager to which the task was submitted
     def submit_finalize(self):
         super().submit_finalize()
         self._add_inputs_outputs(self.manager, *self._fn_def)

taskvine/src/manager/taskvine.h

@@ -361,7 +361,7 @@ the result VINE_RESULT_FORSAKEN.
 @param max_retries The number of retries.
 */
 
-void vine_task_set_max_forsaken(struct vine_task *t, int64_t max_forsaken);
+void vine_task_set_max_forsaken(struct vine_task *t, int64_t max_retries);
 
 /** Specify the amount of disk space required by a task.
 @param t A task object.
@@ -707,7 +707,6 @@ int vine_task_add_environment(struct vine_task *t, struct vine_file *f);
 Typically used to examine an output buffer returned from a file.
 Note that the vfile contents may not be available unless @ref vine_fetch_file
 has previously been called on this object.
-@param m A manager object
 @param f A file object created by @ref vine_declare_buffer.
 @return A constant pointer to the buffer contents, or null if not available.
 */
@@ -773,7 +772,7 @@ struct vine_file *vine_declare_url(
 @param proxy A proxy file object (e.g. from @ref vine_declare_file) of a X509 proxy to use. If NULL, the
 environment variable X509_USER_PROXY and the file "$TMPDIR/$UID" are considered
 in that order. If no proxy is present, the transfer is tried without authentication.
-@param env    If not NULL, an environment file (e.g poncho or starch, see @ref vine_task_add_environment) that contains
+@param env    If not NULL, an environment file (e.g poncho or starch, see @ref vine_task_add_execution_context) that contains
 the xrootd executables. Otherwise assume xrootd is available at the worker.
 @param cache Method for caching file at the workers: never, the default (VINE_CACHE_LEVEL_TASK), to cache only for the
 current manager (VINE_CACHE_LEVEL_WORKFLOW), to cache for the lifetime of the worker (VINE_CACHE_LEVEL_WORKER), or to
@@ -791,7 +790,7 @@ struct vine_file *vine_declare_xrootd(struct vine_manager *m, const char *source
 @param server The chirp server address of the form "hostname[:port"]"
 @param source The name of the file in the server
 @param ticket If not NULL, a file object that provides a chirp an authentication ticket
-@param env    If not NULL, an environment file (e.g poncho or starch, see @ref vine_task_add_environment) that contains
+@param env    If not NULL, an environment file (e.g poncho or starch, see @ref vine_task_add_execution_context) that contains
 the chirp executables. Otherwise assume chirp is available at the worker.
 @param cache Method for caching file at the workers: never, the default (VINE_CACHE_LEVEL_TASK), to cache only for the
 current manager (VINE_CACHE_LEVEL_WORKFLOW), to cache for the lifetime of the worker (VINE_CACHE_LEVEL_WORKER), or to
@@ -1007,9 +1006,9 @@ void vine_manager_remove_library(struct vine_manager *m, const char *name);
 
 /** Find a library template on the manager
 @param m A manager object
-@param name The name of the library of interest
+@param library_name The name of the library of interest
 */
-struct vine_task *vine_manager_find_library_template(struct vine_manager *q, const char *library_name);
+struct vine_task *vine_manager_find_library_template(struct vine_manager *m, const char *library_name);
 
 /** Wait for a task to complete.
 This call will block until either a task has completed, the timeout has expired, or the manager is empty.
@@ -1251,7 +1250,7 @@ int vine_set_category_mode(struct vine_manager *m, const char *category, vine_ca
 
 /** Set a maximum number of tasks of this category that can execute concurrently. If less than 0, unlimited (this is the
 default).
-@param q A manager object.
+@param m A manager object.
 @param category A category name.
 @param max_concurrent Number of maximum concurrent tasks.
 */
@@ -1503,19 +1502,19 @@ void vine_set_runtime_info_path(const char *path);
 /** Sets the directory where a workflow-specific runtime logs are directly written into.
 @param dir A directory
 */
-void vine_set_runtime_info_template(const char *template);
+void vine_set_runtime_info_template(const char *dir);
 
 /** Adds a custom APPLICATION entry to the debug log.
 @param m     Reference to the current manager object.
 @param entry A custom debug message.
 */
-void vine_log_debug_app(struct vine_manager *q, const char *entry);
+void vine_log_debug_app(struct vine_manager *m, const char *entry);
 
 /** Adds a custom APPLICATION entry to the transactions log.
 @param m     Reference to the current manager object.
 @param entry A custom transaction message.
 */
-void vine_log_txn_app(struct vine_manager *q, const char *entry);
+void vine_log_txn_app(struct vine_manager *m, const char *entry);
 
 /** Display internal reference counts for troubleshooting purposes.
  */
@@ -1529,24 +1528,28 @@ char *vine_version_string();
 
 /** Returns path relative to the logs runtime directory
 @param m Reference to the current manager object.
+@param path Target filename.
 @return A string.
 */
 char *vine_get_path_log(struct vine_manager *m, const char *path);
 
 /** Returns path relative to the staging runtime directory
 @param m Reference to the current manager object.
+@param path Target filename.
 @return A string.
 */
 char *vine_get_path_staging(struct vine_manager *m, const char *path);
 
 /** Returns path relative to the library logs runtime directory
 @param m Reference to the current manager object.
+@param path Target filename.
 @return A string.
 */
 char *vine_get_path_library_log(struct vine_manager *m, const char *path);
 
 /** Returns path relative to the cache runtime directory
 @param m Reference to the current manager object.
+@param path Target filename.
 @return A string.
 */
 char *vine_get_path_cache(struct vine_manager *m, const char *path);