Shdoc Requirements

Table of Contents

If you're wondering how to read these documents, see the discussion in the References, under Where To Start.

1 Shdoc Requirements

Require an application which adds non-executable information to a shell function. The main purpose of the added information is to provide:

  • the function's shdoc, comparable to javadoc, pydoc, {any}doc, the descriptive preface of a function's behavior, emphasizing what, rather than how the function performs it task.
  • the function's abstract, the first line of the shdoc

These are the specific requirements

1.1 In-Function requirements

  1. A means of inserting comments into a standard function.
  2. A means to tag certain comments
  3. A tag is an alpha-numeric token accompanied by a uniform syntactic element.
  4. A tag shall be the first blank-separated string of the comment,

1.2 Usage requirements

  1. A means to retrieve all the comments of a function, including:
    • all comments preceding the first executable statement'
    • the first of these, called the abstract
    • all of these less the tagged comments, called the shdoc
    • all comments of an individual tag (see the more reserved token)
  2. A means to produce the comment-free function text (i.e. only the executable code )

  3. reports to include:

    • A one-line report including the function-name <TAB> abstract
    • A multi-line report whose first line is the one-line report, with the remainder of the shdoc tab-indented.

    . + A report listing the tagged lines of a function: 

    function-name <TAB> tag <TAB> subsequent string

1.3 Reserved Tag Tokens

A very few tag tokens are reserved, due to current use:

  • date – the ISO-date format (YYYY-MM-DD) of a change, or storing in a library, which may be followed by string
  • todo – a string indicating a potential change to a function. This is not appropriate for a necessary change.
  • more – a continuation of the immediately preceding tag

The Tag Manual reserves other names. Its first edition includes a comprehensive list of tags in current use.

1.4 Discussion

The shdoc format assumes each line after the abstract uses the more tag

Pay careful attention to the definition of the standard function

1.5 References

1.5.1 Where to Start

The practice documented here is all about developing bash shell functions. In my opinion, the use of functions in bash, while readily accessible, is under-appreciated, under-used. Pick one of these approaches to the material, based on your needs and interests.

  1. Formal Approach

    If you are interested in a more formal approach, choose this reading sequence:

    The Tag Manual discusses uses of a new feature introduced here, the null-command comment. The tag was introduced mostly to provide the shdoc feature, internal documentation, motivated by traditional languages, javadoc, pydoc, …

  2. Shell Programmer

    If you have some shell programming experience, choose this order:

  3. Gaining Experience

    While the material here is not for the beginning shell programmer, the author recommends his e-book Shell Functions, which has a link to a series of YouTube videos on the method. Visiting the videos, you will find a host of other introductions to the shell.

1.5.2 Definitions

Three definitions define sets of functions, distinguishing the need for the collection: the app, family, and library. The library is the most general, the app being the most specific. The relationship is discussed in The Standard Function Library.

Where these definitions appear in requrements documents, they assume a certain implementation, in particular the definition of a tag. Since the null-operator, a gift from the shell designers, uses the colon, it seems appropriate to use the colon as the distinguishing feature of a tag, .e.g. 

date: 2020-02-20  this change ....
  • app – a set of functions collected to serve a set of requirements
  • canonical function – a function when formatted declare -f function_name
  • entry point – in an app, a function called only from the command line,
  • family – a set of functions sharing common stem, e.g. family_subfunction
  • library – a set of functions with zero or more families
  • local function – a function used only within another function
  • null operator – a shell command beginning with a :
  • semantic comment – a shell function which may not display its arguments, or display them on standard error
  • shell script – a shell file, whose first line is a sh-bang: #! env bash
  • shdoc – a function family which implements Shell Documentation, see the Standard Function Library
  • source – a builtin shell command to source or load a function library
  • standard function – a function which meets the requirements of The Function Standard
  • standard library – a library meeting the requirements of The Library Standard
  • subfunction – a member of a function family
  • tag – a colon-terminated first argument to the null command

1.5.3 Documents

These local papers are housed in the author's section of his commonplace book, which references The Function Standard

  1. Standards Documents
  2. Application Requirements
  3. Practice Documents
    • Standard Function Library – A Standard Function Library adhering to the Function and Library Standards, implementing functions which support the preferred behaviors
    • Tag Manual – tag semantics, defining other tags, it's open-ended.
    • Function Practice, A – Applying the lessons of the Standard Function Library
  4. External References
    • Sh-bang – standard starting line of the script file

Author: Marty McGowan

Created: 2020-01-27 Mon 15:03

Validate