Merge pull request #378 from urbanjost/ford-ify

Add ford-compatible documentation to fpm_strings.f90

5 files changed, 182 insertions, 130 deletions

diff --git a/fpm/src/fpm_command_line.f90 b/fpm/src/fpm_command_line.f90
index ac0d595..72a4000 100644
--- a/fpm/src/fpm_command_line.f90
+++ b/fpm/src/fpm_command_line.f90
@@ -15,7 +15,7 @@
 !> wanted command line and the expected default values.
 !> Some of the following points also apply if you add a new option or argument
 !> to an existing *fpm* subcommand.
-!> Add this point you should create a help page for the new command in a simple
+!> At this point you should create a help page for the new command in a simple
 !> catman-like format as well in the ``set_help`` procedure.
 !> Make sure to register new subcommands in the ``fpm-manual`` command by adding
 !> them to the manual character array and in the help/manual case as well.
diff --git a/fpm/src/fpm_compiler.f90 b/fpm/src/fpm_compiler.f90
index 99aa77d..20c6482 100644
--- a/fpm/src/fpm_compiler.f90
+++ b/fpm/src/fpm_compiler.f90
@@ -1,14 +1,18 @@
+!># Define compiler command options
+!!
+!! This module defines compiler options to use for the debug and release builds.
 module fpm_compiler
 use fpm_model, only: fpm_model_t
 use fpm_filesystem, only: join_path
 public  add_compile_flag_defaults
 
 contains
+!> Choose compile flags based on cli settings & manifest inputs
 subroutine add_compile_flag_defaults(build_name,compiler,model)
-! Choose compile flags based on cli settings & manifest inputs
-character(len=*),intent(in) :: build_name, compiler
+character(len=*),intent(in) :: build_name   !! select build from {release,debug}
+character(len=*),intent(in) :: compiler     !! compiler name
+type(fpm_model_t), intent(inout) :: model   !! model to add compiler options to
 
-type(fpm_model_t), intent(inout) :: model
 ! could just be a function to return a string instead of passing model
 ! but likely to change other components like matching C compiler
 
diff --git a/fpm/src/fpm_environment.f90 b/fpm/src/fpm_environment.f90
index 929a704..0408ec4 100644
--- a/fpm/src/fpm_environment.f90
+++ b/fpm/src/fpm_environment.f90
@@ -1,3 +1,7 @@
+!> This module contains procedures that interact with the programming environment.
+!! 
+!! * [get_os_type] -- Determine the OS type
+!! * [get_env] -- return the value of an environment variable
 module fpm_environment
     implicit none
     private
@@ -14,8 +18,8 @@ module fpm_environment
     integer, parameter, public :: OS_SOLARIS = 5
     integer, parameter, public :: OS_FREEBSD = 6
 contains
+    !> Determine the OS type
     integer function get_os_type() result(r)
-        !! Determine the OS type
         !!
         !! Returns one of OS_UNKNOWN, OS_LINUX, OS_MACOS, OS_WINDOWS, OS_CYGWIN,
         !! OS_SOLARIS, OS_FREEBSD.
@@ -106,6 +110,9 @@ contains
         end if
     end function get_os_type
 
+    !> Compare the output of [[get_os_type]] or the optional 
+    !! passed INTEGER value to the value for OS_WINDOWS
+    !! and return .TRUE. if they match and .FALSE. otherwise
     logical function os_is_unix(os) result(unix)
         integer, intent(in), optional :: os
         integer :: build_os
@@ -117,6 +124,7 @@ contains
         unix = os /= OS_WINDOWS
     end function os_is_unix
 
+    !> echo command string and pass it to the system for execution
     subroutine run(cmd,echo)
         character(len=*), intent(in) :: cmd
         logical,intent(in),optional  :: echo
@@ -137,10 +145,15 @@ contains
         end if
     end subroutine run
 
+    !> get named environment variable value. It it is blank or
+    !! not set return the optional default value
     function get_env(NAME,DEFAULT) result(VALUE)
     implicit none
-    character(len=*),intent(in)          :: NAME
+    !> name of environment variable to get the value of
+    character(len=*),intent(in)          :: NAME     
+    !> default value to return if the requested value is undefined or blank
     character(len=*),intent(in),optional :: DEFAULT
+    !> the returned value
     character(len=:),allocatable         :: VALUE
     integer                              :: howbig
     integer                              :: stat
diff --git a/fpm/src/fpm_filesystem.f90 b/fpm/src/fpm_filesystem.f90
index 5811cd4..f9781ab 100644
--- a/fpm/src/fpm_filesystem.f90
+++ b/fpm/src/fpm_filesystem.f90
@@ -1,3 +1,5 @@
+!> This module contains general routines for interacting with the file system
+!!
 module fpm_filesystem
 use,intrinsic :: iso_fortran_env, only : stdin=>input_unit, stdout=>output_unit, stderr=>error_unit
     use fpm_environment, only: get_os_type, &
@@ -15,6 +17,7 @@ use,intrinsic :: iso_fortran_env, only : stdin=>input_unit, stdout=>output_unit,
 contains
 
 
+!> return value of environment variable
 subroutine env_variable(var, name)
    character(len=:), allocatable, intent(out) :: var
    character(len=*), intent(in) :: name
@@ -36,9 +39,9 @@ subroutine env_variable(var, name)
 end subroutine env_variable
 
 
+!> Extract filename from path with/without suffix
 function basename(path,suffix) result (base)
-    ! Extract filename from path with/without suffix
-    !
+ 
     character(*), intent(In) :: path
     logical, intent(in), optional :: suffix
     character(:), allocatable :: base
@@ -71,13 +74,13 @@ function basename(path,suffix) result (base)
 end function basename
 
 
+!> Canonicalize path for comparison
+!! * Handles path string redundancies
+!! * Does not test existence of path
+!!
+!! To be replaced by realpath/_fullname in stdlib_os
+!!
 function canon_path(path) result(canon)
-    ! Canonicalize path for comparison
-    !  Handles path string redundancies
-    !  Does not test existence of path
-    !
-    ! To be replaced by realpath/_fullname in stdlib_os
-    !
     character(*), intent(in) :: path
     character(:), allocatable :: canon
 
@@ -141,9 +144,8 @@ function canon_path(path) result(canon)
 end function canon_path
 
 
+!> Extract dirname from path
 function dirname(path) result (dir)
-    ! Extract dirname from path
-    !
     character(*), intent(in) :: path
     character(:), allocatable :: dir
 
@@ -152,6 +154,7 @@ function dirname(path) result (dir)
 end function dirname
 
 
+!> test if a name matches an existing directory path
 logical function is_dir(dir)
     character(*), intent(in) :: dir
     integer :: stat
@@ -171,9 +174,9 @@ logical function is_dir(dir)
 end function is_dir
 
 
+!> Construct path by joining strings with os file separator
 function join_path(a1,a2,a3,a4,a5) result(path)
-    ! Construct path by joining strings with os file separator
-    !
+
     character(len=*), intent(in)           :: a1, a2
     character(len=*), intent(in), optional :: a3, a4, a5
     character(len=:), allocatable          :: path
@@ -209,8 +212,8 @@ function join_path(a1,a2,a3,a4,a5) result(path)
 end function join_path
 
 
+!> Determine number or rows in a file given a LUN
 integer function number_of_rows(s) result(nrows)
-    ! determine number or rows
     integer,intent(in)::s
     integer :: ios
     character(len=100) :: r
@@ -225,6 +228,7 @@ integer function number_of_rows(s) result(nrows)
 end function number_of_rows
 
 
+!> read lines into an array of TYPE(STRING_T) variables
 function read_lines(fh) result(lines)
     integer, intent(in) :: fh
     type(string_t), allocatable :: lines(:)
@@ -240,6 +244,7 @@ function read_lines(fh) result(lines)
 
 end function read_lines
 
+!> Create a directory. Create subdirectories as needed
 subroutine mkdir(dir)
     character(len=*), intent(in) :: dir
     integer                      :: stat
@@ -263,12 +268,12 @@ subroutine mkdir(dir)
 end subroutine mkdir
 
 
+!> Get file & directory names in directory `dir`.
+!!
+!!  - File/directory names return are relative to cwd, ie. preprended with `dir`
+!!  - Includes files starting with `.` except current directory and parent directory
+!!
 recursive subroutine list_files(dir, files, recurse)
-    ! Get file & directory names in directory `dir`.
-    !
-    !  - File/directory names return are relative to cwd, ie. preprended with `dir`
-    !  - Includes files starting with `.` except current directory and parent directory
-    !
     character(len=*), intent(in) :: dir
     type(string_t), allocatable, intent(out) :: files(:)
     logical, intent(in), optional :: recurse
@@ -329,18 +334,19 @@ recursive subroutine list_files(dir, files, recurse)
 end subroutine list_files
 
 
+!> test if pathname already exists
 logical function exists(filename) result(r)
     character(len=*), intent(in) :: filename
     inquire(file=filename, exist=r)
 end function
 
 
+!> Get a unused temporary filename
+!!  Calls posix 'tempnam' - not recommended, but
+!!   we have no security concerns for this application
+!!   and use here is temporary.
+!! Works with MinGW
 function get_temp_filename() result(tempfile)
-    ! Get a unused temporary filename
-    !  Calls posix 'tempnam' - not recommended, but
-    !   we have no security concerns for this application
-    !   and use here is temporary.
-    ! Works with MinGW
     !
     use iso_c_binding, only: c_ptr, C_NULL_PTR, c_f_pointer
     character(:), allocatable :: tempfile
@@ -374,9 +380,9 @@ function get_temp_filename() result(tempfile)
 end function get_temp_filename
 
 
+!> Replace file system separators for windows
 function windows_path(path) result(winpath)
-    ! Replace file system separators for windows
-    !
+
     character(*), intent(in) :: path
     character(:), allocatable :: winpath
 
@@ -393,9 +399,9 @@ function windows_path(path) result(winpath)
 end function windows_path
 
 
+!> Replace file system separators for unix
 function unix_path(path) result(nixpath)
-    ! Replace file system separators for unix
-    !
+
     character(*), intent(in) :: path
     character(:), allocatable :: nixpath
 
@@ -412,6 +418,7 @@ function unix_path(path) result(nixpath)
 end function unix_path
 
 
+!> read a line of arbitrary length into a CHARACTER variable from the specified LUN
 subroutine getline(unit, line, iostat, iomsg)
 
     !> Formatted IO unit
@@ -453,6 +460,7 @@ subroutine getline(unit, line, iostat, iomsg)
 end subroutine getline
 
 
+!> delete a file by filename
 subroutine delete_file(file)
     character(len=*), intent(in) :: file
     logical :: exist
@@ -464,8 +472,8 @@ subroutine delete_file(file)
     end if
 end subroutine delete_file
 
-subroutine warnwrite(fname,data)
 !> write trimmed character data to a file if it does not exist
+subroutine warnwrite(fname,data)
 character(len=*),intent(in) :: fname
 character(len=*),intent(in) :: data(:)
 
@@ -478,8 +486,8 @@ character(len=*),intent(in) :: data(:)
 
 end subroutine warnwrite
 
+!> procedure to open filename as a sequential "text" file
 subroutine fileopen(filename,lun,ier)
-! procedure to open filename as a sequential "text" file
 
 character(len=*),intent(in)   :: filename
 integer,intent(out)           :: lun
@@ -516,8 +524,8 @@ character(len=256)            :: message
 
 end subroutine fileopen
 
+!> simple close of a LUN.  On error show message and stop (by default)
 subroutine fileclose(lun,ier)
-! simple close of a LUN.  On error show message and stop (by default)
 integer,intent(in)    :: lun
 integer,intent(out),optional :: ier
 character(len=256)    :: message
@@ -535,8 +543,8 @@ integer               :: ios
     endif
 end subroutine fileclose
 
+!> procedure to write filedata to file filename
 subroutine filewrite(filename,filedata)
-! procedure to write filedata to file filename
 
 character(len=*),intent(in)           :: filename
 character(len=*),intent(in)           :: filedata(:)
@@ -560,10 +568,10 @@ character(len=256)                    :: message
 
 end subroutine filewrite
 
+!> Returns string with special characters replaced with an underscore.
+!! For now, only a hyphen is treated as a special character, but this can be
+!! expanded to other characters if needed.
 pure function to_fortran_name(string) result(res)
-    ! Returns string with special characters replaced with an underscore.
-    ! For now, only a hyphen is treated as a special character, but this can be
-    ! expanded to other characters if needed.
     character(*), intent(in) :: string
     character(len(string)) :: res
     character, parameter :: SPECIAL_CHARACTERS(*) = ['-']
diff --git a/fpm/src/fpm_strings.f90 b/fpm/src/fpm_strings.f90
index 7623e43..e074ad8 100644
--- a/fpm/src/fpm_strings.f90
+++ b/fpm/src/fpm_strings.f90
@@ -1,3 +1,32 @@
+!> This module defines general procedures for **string operations** for both CHARACTER and
+!! TYPE(STRING_T) variables
+!
+!>## general routines for performing __string operations__
+!!
+!!### Types
+!! - **TYPE(STRING_T)** define a type to contain strings of variable length
+!!### Type Conversions
+!! - [[F_STRING]]  return Fortran **CHARACTER** variable when given a C-like array of 
+!!                 single characters terminated with a C_NULL_CHAR **CHARACTER**
+!! - [[STR]]  Converts **INTEGER** or** LOGICAL** to **CHARACTER** string
+!!### Case
+!! - [[LOWER]]  Changes a string to lowercase over optional specified column range
+!!### Parsing and joining
+!! - [[SPLIT]]  parse string on delimiter characters and store tokens into an allocatable array
+!! - [[STRING_CAT]]  Concatenate an array of **type(string_t)** into a single **CHARACTER** variable
+!! - [[JOIN]]  append an array of **CHARACTER** variables into a single **CHARACTER** variable 
+!!### Testing
+!! - [[STR_ENDS_WITH]]  test if a **CHARACTER** string or array ends with a specified suffix
+!! - [[STRING_ARRAY_CONTAINS]]  Check if array of **TYPE(STRING_T)** matches a particular **CHARACTER** string
+!! - **OPERATOR(.IN.)**  Check if array of **TYPE(STRING_T)** matches a particular **CHARACTER** string
+!! - [[GLOB]]  function compares text strings, one of which can have wildcards ('*' or '?').
+!!### Miscellaneous
+!! - [[LEN_TRIM]]  Determine total trimmed length of **STRING_T** array
+!! - [[FNV_1A]]  Hash a **CHARACTER(*)** string of default kind or a **TYPE(STRING_T)** array
+!! - [[REPLACE]]  Returns string with characters in charset replaced with target_char.
+!! - [[RESIZE]]  increase the size of a **TYPE(STRING_T)** array by N elements
+!!
+
 module fpm_strings
 use iso_fortran_env, only: int64
 implicit none
@@ -39,6 +68,7 @@ end interface
 
 contains
 
+!> test if a CHARACTER string ends with a specified suffix
 pure logical function str_ends_with_str(s, e) result(r)
     character(*), intent(in) :: s, e
     integer :: n1, n2
@@ -51,6 +81,7 @@ pure logical function str_ends_with_str(s, e) result(r)
     end if
 end function str_ends_with_str
 
+!> test if a CHARACTER string ends with any of an array of suffixs
 pure logical function str_ends_with_any(s, e) result(r)
     character(*), intent(in) :: s
     character(*), intent(in) :: e(:)
@@ -67,6 +98,8 @@ pure logical function str_ends_with_any(s, e) result(r)
 
 end function str_ends_with_any
 
+!> return Fortran character variable when given a C-like array of
+!! single characters terminated with a C_NULL_CHAR character
 function f_string(c_string)
     use iso_c_binding
     character(len=1), intent(in) :: c_string(:)
@@ -128,10 +161,10 @@ pure function fnv_1a_string_t(input, seed) result(hash)
 end function fnv_1a_string_t
 
 
+ !>Author: John S. Urban
+ !!License: Public Domain
+ !! Changes a string to lowercase over optional specified column range
 elemental pure function lower(str,begin,end) result (string)
-    ! Changes a string to lowercase over specified range
-    ! Author: John S. Urban
-    ! License: Public Domain
 
     character(*), intent(In)     :: str
     character(len(str))          :: string
@@ -161,9 +194,9 @@ elemental pure function lower(str,begin,end) result (string)
 end function lower
 
 
+!> Check if array of TYPE(STRING_T) matches a particular CHARACTER string
+!!
 logical function string_array_contains(search_string,array)
-    ! Check if array of string_t contains a particular string
-    !
     character(*), intent(in) :: search_string
     type(string_t), intent(in) :: array(:)
 
@@ -175,7 +208,7 @@ logical function string_array_contains(search_string,array)
 end function string_array_contains
 
 !> Concatenate an array of type(string_t) into
-!>  a single character
+!>  a single CHARACTER variable
 function string_cat(strings,delim) result(cat)
     type(string_t), intent(in) :: strings(:)
     character(*), intent(in), optional :: delim
@@ -216,20 +249,19 @@ pure function string_len_trim(strings) result(n)
 
 end function string_len_trim
 
+!>Author: John S. Urban
+!!License: Public Domain
+!! parse string on delimiter characters and store tokens into an allocatable array
 subroutine split(input_line,array,delimiters,order,nulls)
-    ! parse string on delimiter characters and store tokens into an allocatable array"
-    ! Author: John S. Urban
-    ! License: Public Domain
-
-
-    !  given a line of structure " par1 par2 par3 ... parn " store each par(n) into a separate variable in array.
-    !    o by default adjacent delimiters in the input string do not create an empty string in the output array
-    !    o no quoting of delimiters is supported
-    character(len=*),intent(in)              :: input_line  ! input string to tokenize
-    character(len=*),optional,intent(in)     :: delimiters  ! list of delimiter characters
-    character(len=*),optional,intent(in)     :: order       ! order of output array sequential|[reverse|right]
-    character(len=*),optional,intent(in)     :: nulls       ! return strings composed of delimiters or not ignore|return|ignoreend
-    character(len=:),allocatable,intent(out) :: array(:)    ! output array of tokens
+    !! given a line of structure " par1 par2 par3 ... parn " store each par(n) into a separate variable in array.
+    !!
+    !! * by default adjacent delimiters in the input string do not create an empty string in the output array
+    !! * no quoting of delimiters is supported
+    character(len=*),intent(in)              :: input_line  !! input string to tokenize
+    character(len=*),optional,intent(in)     :: delimiters  !! list of delimiter characters
+    character(len=*),optional,intent(in)     :: order       !! order of output array sequential|[reverse|right]
+    character(len=*),optional,intent(in)     :: nulls       !! return strings composed of delimiters or not ignore|return|ignoreend
+    character(len=:),allocatable,intent(out) :: array(:)    !! output array of tokens
 
     integer                       :: n                      ! max number of strings INPUT_LINE could split into if all delimiter
     integer,allocatable           :: ibegin(:)              ! positions in input string where tokens start
@@ -334,8 +366,8 @@ subroutine split(input_line,array,delimiters,order,nulls)
     enddo
 end subroutine split
 
+!> Returns string with characters in charset replaced with target_char.
 pure function replace(string, charset, target_char) result(res)
-    ! Returns string with characters in charset replaced with target_char.
     character(*), intent(in) :: string
     character, intent(in) :: charset(:), target_char
     character(len(string)) :: res
@@ -348,6 +380,7 @@ pure function replace(string, charset, target_char) result(res)
     end do
 end function replace
 
+!> increase the size of a TYPE(STRING_T) array by N elements
 subroutine resize_string(list, n)
   !> Instance of the array to be resized
   type(string_t), allocatable, intent(inout) :: list(:)
@@ -383,14 +416,14 @@ subroutine resize_string(list, n)
 
 end subroutine resize_string
 
-pure function join(str,sep,trm,left,right,start,end) result (string)
-!>
-!!##NAME
+!>AUTHOR: John S. Urban
+!!LICENSE: Public Domain
+!!## NAME
 !!    join(3f) - [fpm_strings:EDITING] append CHARACTER variable array into
 !!    a single CHARACTER variable with specified separator
 !!    (LICENSE:PD)
 !!
-!!##SYNOPSIS
+!!## SYNOPSIS
 !!
 !!    pure function join(str,sep,trm,left,right,start,end) result (string)
 !!
@@ -403,13 +436,13 @@ pure function join(str,sep,trm,left,right,start,end) result (string)
 !!     character(len=*),intent(in),optional :: end
 !!     character(len=:),allocatable         :: string
 !!
-!!##DESCRIPTION
-!!      JOIN(3f) appends the elements of a CHARACTER array into a single
-!!      CHARACTER variable, with elements 1 to N joined from left to right.
-!!      By default each element is trimmed of trailing spaces and the
-!!      default separator is a null string.
+!!## DESCRIPTION
+!!   JOIN(3f) appends the elements of a CHARACTER array into a single
+!!   CHARACTER variable, with elements 1 to N joined from left to right.
+!!   By default each element is trimmed of trailing spaces and the
+!!   default separator is a null string.
 !!
-!!##OPTIONS
+!!## OPTIONS
 !!      STR(:)  array of CHARACTER variables to be joined
 !!      SEP     separator string to place between each variable. defaults
 !!              to a null string.
@@ -420,50 +453,47 @@ pure function join(str,sep,trm,left,right,start,end) result (string)
 !!      TRM     option to trim each element of STR of trailing
 !!              spaces. Defaults to .TRUE.
 !!
-!!##RESULT
+!!## RESULT
 !!      STRING  CHARACTER variable composed of all of the elements of STR()
 !!              appended together with the optional separator SEP placed
 !!              between the elements.
 !!
-!!##EXAMPLE
+!!## EXAMPLE
 !!
 !!  Sample program:
-!!
-!!   program demo_join
-!!   use fpm_strings, only: join
-!!   implicit none
-!!   character(len=:),allocatable  :: s(:)
-!!   character(len=:),allocatable  :: out
-!!   integer                       :: i
-!!     s=[character(len=10) :: 'United',' we',' stand,', &
-!!     & ' divided',' we fall.']
-!!     out=join(s)
-!!     write(*,'(a)') out
-!!     write(*,'(a)') join(s,trm=.false.)
-!!     write(*,'(a)') (join(s,trm=.false.,sep='|'),i=1,3)
-!!     write(*,'(a)') join(s,sep='<>')
-!!     write(*,'(a)') join(s,sep=';',left='[',right=']')
-!!     write(*,'(a)') join(s,left='[',right=']')
-!!     write(*,'(a)') join(s,left='>>')
-!!   end program demo_join
+!!```fortran
+!!    program demo_join
+!!    use fpm_strings, only: join
+!!    implicit none
+!!    character(len=:),allocatable  :: s(:)
+!!    character(len=:),allocatable  :: out
+!!    integer                       :: i
+!!      s=[character(len=10) :: 'United',' we',' stand,', &
+!!      & ' divided',' we fall.']
+!!      out=join(s)
+!!      write(*,'(a)') out
+!!      write(*,'(a)') join(s,trm=.false.)
+!!      write(*,'(a)') (join(s,trm=.false.,sep='|'),i=1,3)
+!!      write(*,'(a)') join(s,sep='<>')
+!!      write(*,'(a)') join(s,sep=';',left='[',right=']')
+!!      write(*,'(a)') join(s,left='[',right=']')
+!!      write(*,'(a)') join(s,left='>>')
+!!    end program demo_join
+!!```fortran
 !!
 !!  Expected output:
 !!
-!!   United we stand, divided we fall.
-!!   United     we        stand,    divided   we fall.
-!!   United    | we       | stand,   | divided  | we fall.
-!!   United    | we       | stand,   | divided  | we fall.
-!!   United    | we       | stand,   | divided  | we fall.
-!!   United<> we<> stand,<> divided<> we fall.
-!!   [United];[ we];[ stand,];[ divided];[ we fall.]
-!!   [United][ we][ stand,][ divided][ we fall.]
-!!   >>United>> we>> stand,>> divided>> we fall.
-!!
-!!##AUTHOR
-!!    John S. Urban
+!!    United we stand, divided we fall.
+!!    United     we        stand,    divided   we fall.
+!!    United    | we       | stand,   | divided  | we fall.
+!!    United    | we       | stand,   | divided  | we fall.
+!!    United    | we       | stand,   | divided  | we fall.
+!!    United<> we<> stand,<> divided<> we fall.
+!!    [United];[ we];[ stand,];[ divided];[ we fall.]
+!!    [United][ we][ stand,][ divided][ we fall.]
+!!    >>United>> we>> stand,>> divided>> we fall.
 !!
-!!##LICENSE
-!!    Public Domain
+pure function join(str,sep,trm,left,right,start,end) result (string)
 
 ! @(#)join(3f): append an array of character variables with specified separator into a single CHARACTER variable
 
@@ -503,29 +533,29 @@ character(len=:),allocatable         :: right_local
    if(present(end))string=string//end
 end function join
 
-function glob(tame,wild)
-!>
-!!##NAME
+!>##AUTHOR John S. Urban
+!!##LICENSE Public Domain
+!!## NAME
 !!    glob(3f) - [fpm_strings:COMPARE] compare given string for match to
 !!    pattern which may contain wildcard characters
 !!    (LICENSE:PD)
 !!
-!!##SYNOPSIS
+!!## SYNOPSIS
 !!
 !!    logical function glob(string, pattern )
 !!
 !!     character(len=*),intent(in) :: string
 !!     character(len=*),intent(in) :: pattern
 !!
-!!##DESCRIPTION
-!!    glob(3f) compares given STRING for match to PATTERN which may
-!!    contain wildcard characters.
+!!## DESCRIPTION
+!!   glob(3f) compares given STRING for match to PATTERN which may
+!!   contain wildcard characters.
 !!
-!!    In this version to get a match the entire string must be described
-!!    by PATTERN. Trailing whitespace is significant, so trim the input
-!!    string to have trailing whitespace ignored.
+!!   In this version to get a match the entire string must be described
+!!   by PATTERN. Trailing whitespace is significant, so trim the input
+!!   string to have trailing whitespace ignored.
 !!
-!!##OPTIONS
+!!## OPTIONS
 !!    string   the input string to test to see if it contains the pattern.
 !!    pattern  the following simple globbing options are available
 !!
@@ -537,7 +567,7 @@ function glob(tame,wild)
 !!             o There is no escape character, so matching strings with
 !!               literal question mark and asterisk is problematic.
 !!
-!!##EXAMPLES
+!!## EXAMPLES
 !!
 !!   Example program
 !!
@@ -729,21 +759,18 @@ function glob(tame,wild)
 !!
 !!   Expected output
 !!
-!!##AUTHOR
-!!   John S. Urban
 !!
-!!##REFERENCE
+!!## REFERENCE
 !!   The article "Matching Wildcards: An Empirical Way to Tame an Algorithm"
 !!   in Dr Dobb's Journal, By Kirk J. Krauss, October 07, 2014
 !!
-!!##LICENSE
-!!   Public Domain
+function glob(tame,wild)
 
 ! @(#)fpm_strings::glob(3f): function compares text strings, one of which can have wildcards ('*' or '?').
 
-logical                    :: glob
-character(len=*)           :: tame       ! A string without wildcards
-character(len=*)           :: wild       ! A (potentially) corresponding string with wildcards
+logical                    :: glob       !! result of test
+character(len=*)           :: tame       !! A string without wildcards to compare to the globbing expression
+character(len=*)           :: wild       !! A (potentially) corresponding string with wildcards
 character(len=len(tame)+1) :: tametext
 character(len=len(wild)+1) :: wildtext
 character(len=1),parameter :: NULL=char(0)
@@ -829,8 +856,8 @@ character(len=:),allocatable :: tbookmark, wbookmark
    enddo
 end function glob
 
+!> Returns the length of the string representation of 'i'
 pure integer function str_int_len(i) result(sz)
-! Returns the length of the string representation of 'i'
 integer, intent(in) :: i
 integer, parameter :: MAX_STR = 100
 character(MAX_STR) :: s
@@ -840,15 +867,15 @@ write(s, '(i0)') i
 sz = len_trim(s)
 end function
 
+!> Converts integer "i" to string
 pure function str_int(i) result(s)
-! Converts integer "i" to string
 integer, intent(in) :: i
 character(len=str_int_len(i)) :: s
 write(s, '(i0)') i
 end function
 
+!> Returns the length of the string representation of 'i'
 pure integer function str_int64_len(i) result(sz)
-! Returns the length of the string representation of 'i'
 integer(int64), intent(in) :: i
 integer, parameter :: MAX_STR = 100
 character(MAX_STR) :: s
@@ -858,15 +885,15 @@ write(s, '(i0)') i
 sz = len_trim(s)
 end function
 
+!> Converts integer "i" to string
 pure function str_int64(i) result(s)
-! Converts integer "i" to string
 integer(int64), intent(in) :: i
 character(len=str_int64_len(i)) :: s
 write(s, '(i0)') i
 end function
 
+!> Returns the length of the string representation of 'l'
 pure integer function str_logical_len(l) result(sz)
-! Returns the length of the string representation of 'l'
 logical, intent(in) :: l
 if (l) then
     sz = 6
@@ -875,8 +902,8 @@ else
 end if
 end function
 
+!> Converts logical "l" to string
 pure function str_logical(l) result(s)
-! Converts logical "l" to string
 logical, intent(in) :: l
 character(len=str_logical_len(l)) :: s
 if (l) then