Enforce documentation of all public functions

Signed-off-by: Alexey Gladkov <[email protected]>

Makefile

@@ -82,6 +82,20 @@ release: $(PROJECT)-$(VERSION).tar.sign
 
 check:
 	@cd tests; ./runtests
+	@sed -n -e 's/^## \([^[:space:]]\+\)$$/\1/p'   docs/shell-* |sort -uo $(CURDIR)/.shell-funcs-documented
+	@sed -n -e 's/^\([A-Za-z][A-Za-z0-9_]\+\)().*/\1/p' shell-* |sort -uo $(CURDIR)/.shell-funcs
+	@comm -13 $(CURDIR)/.shell-funcs-documented $(CURDIR)/.shell-funcs > $(CURDIR)/.shell-funcs-not-documented
+	@rc=0; \
+	if [ "$$(wc -l < $(CURDIR)/.shell-funcs-not-documented)" != "0" ]; then \
+	    echo >&2 "ERROR: some functions are not documented:"; \
+	    cat $(CURDIR)/.shell-funcs-not-documented; \
+	    rc=1; \
+	fi; \
+	rm -f -- \
+	    $(CURDIR)/.shell-funcs-documented \
+	    $(CURDIR)/.shell-funcs-not-documented \
+	    $(CURDIR)/.shell-funcs; \
+	exit $$rc;
 
 verify:
 	@for f in shell-*; do \

docs/shell-args.md

@@ -42,6 +42,12 @@ this function can display error message.
 Function to parse common arguments (*quiet*, *verbose*, *version*, *help*). Using this
 function requires the definition of additional functions: *show_help*, *show_version*.
 
+## show_help
+This stub function must be created by the user.
+
+## print_version
+This stub function must be created by the user.
+
 # ENVIRONMENT
 
 *getopt_common_opts*     - short (one-character) *getopt (1)* options to parse common arguments ("q,v,V,h").

docs/shell-git-config.md

@@ -4,8 +4,8 @@ shell-git-config(3)
 
 git_config_append, git_config_count, git_config_get, git_config_list,
 git_config_location_exists, git_config_parse, git_config_set,
-git_config_unset, git_config_env, git_config_get_var, git_config_get_section - collection
-of functions to work with a git-like config files
+git_config_unset, git_config_env, git_config_foreach, git_config_get_var,
+git_config_get_subsections - collection of functions to work with a git-like config files
 
 # SYNOPSIS
 
@@ -15,9 +15,11 @@ of functions to work with a git-like config files
 - git_config_list file [name]
 - git_config_location_exists file name
 - git_config_parse file
+- git_config_parse_file file
 - git_config_set file name value
 - git_config_unset file name [value]
 - git_config_env file
+- git_config_foreach [name] [custom_handler]
 - git_config_get_var retname section subsection name [{first|last|all=DELIM}]
 - git_config_get_subsections section
 
@@ -48,6 +50,12 @@ Function checks whether there is a specified variable in the configuration.
 ## git_config_parse
 Function lists all names and variables in tab separated form.
 
+## git_config_parse_file
+Parses the git-like config file and calls *git_config_handler* for every value.
+
+## git_config_handler
+Default handler for *git_config_parse_file*.
+
 ## git_config_set
 Function sets or adds *value* into config *file* with given *name*.
 
@@ -56,12 +64,28 @@ Function removes variable by *name* and optionally by *value*.
 
 ## git_config_env
 Function parses config *file* and store it as shell variables to improve future access to values.
+This is another way to get values from the config. It requires more memory since it places the config
+parameters in shell variables. This can be useful if you often access config variables.
+
+## git_config_foreach
+Lists of variables speciRequires file parsing function.fied in the config.
+Uses the result of parsing a file by the *git_config_env*.
+
+## git_config_foreach_handler
+Default handler for *git_config_foreach*.
+This function may be overridden.
 
 ## git_config_get_var
 Function stores value of config value into the *retname* variable.
+Uses the result of parsing a file by the *git_config_env*.
 
 ## git_config_get_subsections
 Function walkthrough all subsections in *section* and call *git_config_get_subsections_handler* function.
+Uses the result of parsing a file by the *git_config_env*.
+
+## git_config_get_subsections_handler
+Default handler for *git_config_get_subsections*.
+This function may be overridden.
 
 # ENVIRONMENT
 

docs/shell-mail-address.md

@@ -0,0 +1,24 @@
+shell-mail-address(3)
+
+# NAME
+
+valid_email - function for the simplest email address validation
+
+# SYNOPSIS
+
+- valid_email string
+
+# DESCRIPTION
+
+## valid_email
+function for the simplest email address validation. It checks for valid characters in
+the name and for valid domains.
+This function is too naive and needs to be improved or removed.
+
+# AUTHOR
+Authors and contributors of the programs included in the *libshell* package are listed
+in the COPYING file.
+
+# BUGS
+Report bugs to the authors.
+

docs/shell-quote.md

@@ -55,6 +55,9 @@ quote_shell_args args "$var_args"
 eval "set -- $args"
 ```
 
+## string_quote_remove
+Obsolete function. You shouldn't use it.
+
 # AUTHOR
 Authors and contributors of the programs included in the *libshell* package are listed
 in the COPYING file.

docs/shell-string.md

@@ -0,0 +1,23 @@
+shell-string(3)
+
+# NAME
+
+fill_mask - functions for working with strings
+
+# SYNOPSIS
+
+- fill_mask var str [full-length]
+
+# DESCRIPTION
+
+## fill_mask
+Creates a mask of equal length string. This pattern is used to process a string
+one character at a time.
+
+# AUTHOR
+Authors and contributors of the programs included in the *libshell* package are listed
+in the COPYING file.
+
+# BUGS
+Report bugs to the authors.
+

shell-git-config

@@ -608,6 +608,7 @@ git_config_get_var()
 	eval "$__git_config_get_var_ret=\"\$__git_config_get_var_v\""
 }
 
+### Usage: git_config_foreach [name] [custom_handler]
 git_config_foreach_handler()
 {
 	printf '%s=%s\n' "$1" "$2"