This article is a continuation of the previous article. We will be taking the previous script and using it to build on the concepts we will learning in this article.
Documentation in scripts
As you must have observed, our script has already grown to a fairly large one. It still performs the same task we intended it to perform, but there are many more features and capabilities in it. As our script grows it becomes more and more difficult for us to understand what is happening and why. Of course, since we have written the script it is a lot easier for us to understand. But let’s suppose there is a colleague of yours that is reading this script. He/she might have a more difficult time trying to understand the purpose of the script. In fact, even if you attempted to read your own script, say after a break of 6 months, you will take some time understanding why exactly you wrote a piece of code.
A good way to address these issues is to document our code. Documentation gives the creator/editor of the script a chance to explain in simple terms what he/she intendeds to do and potentially why they did a particular thing.
What should be documented?
This is how the documentation template looks.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| #!/bin/bash | |
| #------------------------------------------------------------------------------------------------- | |
| #NAME: <#documentation#> | |
| #AUTHOR: <#author name#> | |
| #CONTACT: <#email#> | |
| #DATE: <#date#> | |
| #WEBSITE: <#url#> | |
| #------------------------------------------------------------------------------------------------- | |
| #LEGAL DISCLAIMER -------------------------------------------------------------------------------- | |
| #THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | |
| #IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | |
| #FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | |
| #AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | |
| #LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | |
| #OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | |
| #SOFTWARE. | |
| #------------------------------------------------------------------------------------------------- | |
| #LICENSE/TERMS AND CONDITIONS -------------------------------------------------------------------- | |
| #MIT License | |
| #Copyright (c) <#2021#> <#company name#> | |
| #Permission is hereby granted, free of charge, to any person obtaining a copy | |
| #of this software and associated documentation files (the "Software"), to deal | |
| #in the Software without restriction, including without limitation the rights | |
| #to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | |
| #copies of the Software, and to permit persons to whom the Software is | |
| #furnished to do so, subject to the following conditions: | |
| #The above copyright notice and this permission notice shall be included in all | |
| #copies or substantial portions of the Software. | |
| #------------------------------------------------------------------------------------------------- | |
| #ABOUT ------------------------------------------------------------------------------------------- | |
| #This give basic information about the file such as | |
| # <#filename#> | |
| # <#version#> | |
| #------------------------------------------------------------------------------------------------- | |
| #DESCRIPTION ------------------------------------------------------------------------------------- | |
| # Here you will give a brief decription of what your script does. Here are some of the things that you can mention. | |
| # <#- Intended purpose#> | |
| # <#- Situations when you can use this#> | |
| # <#- The target computers where this should ideally run on.#> | |
| #------------------------------------------------------------------------------------------------- | |
| #USAGE ------------------------------------------------------------------------------------------- | |
| # This is where you give instructions on how to run the script. These could include: | |
| # <#- Command#> | |
| # <#- Available options#> | |
| # <#- Getting help#> | |
| #------------------------------------------------------------------------------------------------- | |
| #WARNING/CAUTION --------------------------------------------------------------------------------- | |
| #****************************************************************************************************************** | |
| #****************************************************************************************************************** | |
| #****************************************************************************************************************** | |
| #****************************************************************************************************************** | |
| # SOME SCRIPTS MAY MAKE SIGNIFICANT AND/OR IRREVERSIBLE CHANGES TO THE SYSTEM. | |
| # THIS IS A GOOD PLACE TO MENTION THOSE ACTIONS. TRY TO DAW THE READERS ATTENTION OUT HERE. | |
| #****************************************************************************************************************** | |
| #****************************************************************************************************************** | |
| #****************************************************************************************************************** | |
| #****************************************************************************************************************** | |
| #------------------------------------------------------------------------------------------------- | |
| #INSTALLATION ------------------------------------------------------------------------------------ | |
| # Instructions for placing the script in the correct place are listed here. | |
| # Location: <#/Library/Scripts/#> | |
| # Permissions: <#rwx r-x r-x#> | |
| #------------------------------------------------------------------------------------------------- | |
| #REQUIREMENTS ------------------------------------------------------------------------------------ | |
| # Specify what is required | |
| # Shell: <#/bin/zsh#> | |
| # OS: <#macOS Big Sur 11.x#> | |
| # Dependencies: <#Other tools#> | |
| #------------------------------------------------------------------------------------------------- | |
| #HELP/SUPPORT ------------------------------------------------------------------------------------ | |
| # Give information about how users can get help about your script. This can onclude the use of help options or even man pages. | |
| # Mention how they could access the same. | |
| # For example: | |
| # You can get help by running the following commands. | |
| # <#<command> -h#> | |
| # <#<command> -help#> | |
| # OR | |
| # <#man <command>#> | |
| #------------------------------------------------------------------------------------------------- | |
| #HISTORY ----------------------------------------------------------------------------------------- | |
| # ------------------------------------------------------------------------------------------------ | |
| # This is a good place to give version history. This helps the user of the script or any future modifiers of the script understand how the script evolved. | |
| #------------------------------------------------------------------------------------------------- | |
| #------------------------------------------------------------------------------------------------- | |
| # ------------------------------ SCRIPT STARTS HERE ---------------------------------------------- | |
| #------------------------------------------------------------------------------------------------- | |
| #------------------------------------------------------------------------------------------------- | |
| #------------------------------------------------------------------------------------------------- | |
| #------------------------------------------------------------------------------------------------- | |
| #------------------------------------------------------------------------------------------------- | |
| #------------------------------------------------------------------------------------------------- | |
| # ------------------------------ END OF SCRIPT --------------------------------------------------- |
Let us look at some of the things that can be offered.
| Item | Description |
|---|---|
| Ownership | This is where we provide details about the person who originally created the script. There might be more than one author involved. Also, it would be nice to maintain a history of people who have modified the script in any way. |
| Legal disclaimers and License terms | This is where you specify any disclaimers or warning that you wish to provide to anyone who wishes to use the script. You may also include license terms incase you wish to share the script with a wider audience. |
| Description | Of all the pieces this is one of the most important components. This section actually describes the scope and purpose of the script. Anyone who is using the script will probable be looking at this section first. |
| Usage | Use this section to provide information about how this script should be used. You could also provide information about the location of the script. |
| Warning | The idea behind this section is to provide the user information about possible issues with the script. Some examples of this would include: bugs, edge cases, expected supporting assets. Anything that is necessary for the script to run without issues. |
| Installation | This is where information for placing the script in the correct place with the correct permissions are provided. |
| Requirements | Any assets, resources or other items that may be required to run the script. |
| Help and Support | Information about where the user of the script can get more help or how they can get more help is provided here. |
| History | This section gives information about who modified the script, when they did it, along with the version number. This information may also be available via a version control tool such as Git. However, it may not be the case with every user of the script. In any case it is a good idea to also keep the history in the script. |
Offering help
In most situations documentation is enough. But in some situations it may not be possible to read the script. This could be because the user may not have permissions to read the script. Another good way to provide information would be by providing a mechanism to get help for this command.
This is most commonly achieved by providing an option to out script either as -h or -help.
The script has now been modified to support this. It essentially prints a message on the screen if it sees the -h or the -help option.
This is how your final code should look.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| #!/bin/zsh | |
| #------------------------------------------------------------------------------------------------- | |
| #NAME: Folder creator | |
| #AUTHOR: Arun Patwardhan | |
| #CONTACT: arun@amaranthine.co.in | |
| #DATE: 10th August 2021 | |
| #WEBSITE: https://github.com/AmaranthineTech/ShellScripts | |
| #------------------------------------------------------------------------------------------------- | |
| #LEGAL DISCLAIMER -------------------------------------------------------------------------------- | |
| #THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | |
| #IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | |
| #FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | |
| #AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | |
| #LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | |
| #OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | |
| #SOFTWARE. | |
| #------------------------------------------------------------------------------------------------- | |
| #LICENSE/TERMS AND CONDITIONS -------------------------------------------------------------------- | |
| #MIT License | |
| #Copyright (c) Amaranthine 2021. | |
| #Permission is hereby granted, free of charge, to any person obtaining a copy | |
| #of this software and associated documentation files (the "Software"), to deal | |
| #in the Software without restriction, including without limitation the rights | |
| #to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | |
| #copies of the Software, and to permit persons to whom the Software is | |
| #furnished to do so, subject to the following conditions: | |
| #The above copyright notice and this permission notice shall be included in all | |
| #copies or substantial portions of the Software. | |
| #------------------------------------------------------------------------------------------------- | |
| #ABOUT ------------------------------------------------------------------------------------------- | |
| # fileCreator.zsh | |
| # 1.3 | |
| #------------------------------------------------------------------------------------------------- | |
| #DESCRIPTION ------------------------------------------------------------------------------------- | |
| # - THis script is intended for creating the custom folders that are required on all corporate computers. | |
| # - Run this script on a new computer or a computer being reassigned to another employee. | |
| # - This script can run on all computers. | |
| #------------------------------------------------------------------------------------------------- | |
| #USAGE ------------------------------------------------------------------------------------------- | |
| # - To create folders with default names run the command: ./folderCreator.zsh | |
| # - To define your own folder names: ./folderCreator.zsh <folder1> <folder2> <folder3> | |
| # - Available options : Only the help option is available | |
| # - Getting help : Use the -h or the -help options to get more information. Or you can use the man command to view the man page. | |
| #------------------------------------------------------------------------------------------------- | |
| #WARNING/CAUTION --------------------------------------------------------------------------------- | |
| #****************************************************************************************************************** | |
| #****************************************************************************************************************** | |
| #****************************************************************************************************************** | |
| #****************************************************************************************************************** | |
| # This script doesn't perform any validation of the folder names being passed in by the user. | |
| # If the script does not see the -h or the -help options then it will assume that the data being passed in is the name of the folder. | |
| # The user of the script must ensure that the desired folder names are passed in. | |
| #****************************************************************************************************************** | |
| #****************************************************************************************************************** | |
| #****************************************************************************************************************** | |
| #****************************************************************************************************************** | |
| #------------------------------------------------------------------------------------------------- | |
| #INSTALLATION ------------------------------------------------------------------------------------ | |
| # Instructions for placing the script in the correct place are listed here. | |
| # Location: /Library/Scripts/ | |
| # Permissions: rwx r-x r-x | |
| #------------------------------------------------------------------------------------------------- | |
| #REQUIREMENTS ------------------------------------------------------------------------------------ | |
| # Shell: /bin/zsh | |
| # OS: macOS Big Sur 11.4 or later | |
| # Dependencies: None | |
| #------------------------------------------------------------------------------------------------- | |
| #HELP/SUPPORT ------------------------------------------------------------------------------------ | |
| # You can get help by running the following commands. | |
| # ./folderCreator.zsh -h | |
| # ./folderCreator.zsh -help | |
| # OR | |
| # man folderCreator.zsh | |
| # You can also view the log file for the same at: ~/Library/Logs/folderCreator_log_v1-3.log | |
| #------------------------------------------------------------------------------------------------- | |
| #HISTORY ----------------------------------------------------------------------------------------- | |
| # ------------------------------------------------------------------------------------------------ | |
| # Version 1.0: Basic script which creates the folders | |
| # Version 1.1: Gives user the ability to specify the folder names at run time. | |
| # Version 1.2: Adds safety checks to the scripts | |
| # Version 1.3: Includes documentation as well as ability to get help. | |
| #------------------------------------------------------------------------------------------------- | |
| #------------------------------------------------------------------------------------------------- | |
| # ------------------------------ SCRIPT STARTS HERE ---------------------------------------------- | |
| #------------------------------------------------------------------------------------------------- | |
| #------------------------------------------------------------------------------------------------- | |
| #------------------------------------------------------------------------------------------------- | |
| #These are the default values used for the folder names incase the user doesn't provide any. | |
| TOOLS_FOLDER="Tools" | |
| REPORTS_FOLDER="Reports" | |
| HELP_FOLDER="Help" | |
| #Script version number | |
| VERSION_NUMBER="1.3" | |
| #Command name | |
| COMMAND_NAME="folderCreator.zsh" | |
| #1. Check to see if the user is asking for help. In which case we will have to provide information about the command. | |
| if [[ $1 == "-h" ]] || [[ $1 == "-help" ]]; then | |
| echo "ABOUT | |
| ----- | |
| fileCreator_v1-3.zsh | |
| Version $VERSION_NUMBER | |
| NAME | |
| ---- | |
| $COMMAND_NAME — Folder creation utility SYNOPSIS | |
| $COMMAND_NAME folder names [ verbs ] | |
| DESCRIPTION | |
| ----------- | |
| $COMMAND_NAME creates 3 folders in the home folder. In case the folder names are not provided then the command will create folders with default names 'Tools', 'Reports', \"Help\". | |
| There is also the option of getting help via the help verb. | |
| - This script is intended for creating the custom folders that are required on all corporate computers. | |
| - Run this script on a new computer or a computer being reassigned to another employee. | |
| - This script can run on all computers. | |
| VERBS | |
| ----- | |
| [ −h −help] Both the options are used to invoke the help documentation. | |
| [ −v −version] Both the options are used to get the version number of the folderCreator command. | |
| REQUIREMENTS | |
| ------------ | |
| The following are the minimum requirements to get the script running. | |
| Shell:\t\t zsh | |
| OS:\t\t macOS Big Sur 11.4 or later | |
| Dependencies:\t None | |
| INSTALLATION | |
| ------------ | |
| $COMMAND_NAME can be installed anywhere you wish. However, there are certain locations that are recommended. | |
| Location:\t /Library/Scripts/ | |
| Permissions: \t rwxr-xr-x | |
| USAGE | |
| ----- | |
| $COMMAND_NAME folder1 folder2 folder3 | |
| Will create folders with your own names. | |
| $COMMAND_NAME -h OR $COMMAND_NAME -help | |
| Will invoke the help utility. | |
| $COMMAND_NAME -v OR $COMMAND_NAME -version | |
| will print the version number in stdout. | |
| WARNING/CAUTION | |
| --------------- | |
| $COMMAND_NAME does not perform any validation of names. The only options that folderCreator accepts are -h and -help verbs or the -v and -version verbs. If the script does not see the -h , -help or the -v , -version options then it will assume that the data being passed in is the name of the folder. The user of the folderCreator command must ensure that the desired folder names are passed in. | |
| EXAMPLES | |
| -------- | |
| $COMMAND_NAME Resources Results Assistant | |
| This will create 3 folders Resources , Results , Assistant , in the user’s home folder. | |
| $COMMAND_NAME | |
| This will create 3 folders with the default names | |
| $COMMAND_NAME Apps | |
| This will use the Apps name for the first folder but the default names for the last 2 folders. | |
| DIAGNOSTICS | |
| ----------- | |
| The script produces a log file called ~/Library/Logs/folderCreator_log_v1-x.log | |
| This file is typically located in the user’s home folder log folder. The x represents the version number of $COMMAND_NAME | |
| You can view the logs for each respective version. | |
| COPYRIGHT | |
| --------- | |
| Copyright (c) Amaranthine 2015-2021. All rights reserved. https://amaranthine.in | |
| EXIT STATUS | |
| ----------- | |
| In most situations, $COMMAND_NAME exits 0 on success" | |
| exit 0 | |
| fi | |
| echo "$(date) Running script $0 to create folders." | |
| echo "" | |
| #2. Check to see if the version number is | |
| if [[ $1 == "-version" ]] || [[ $1 == "-v" ]]; then | |
| echo "Version: $VERSION_NUMBER" | |
| exit 0 | |
| fi | |
| #3. The following if statements check to see if the script is receiving any arguments. It then picks those arguments and assigns them to the respective variables for use in the script. | |
| if [[ $1 != "" ]]; then | |
| TOOLS_FOLDER=$1 | |
| fi | |
| if [[ $2 != "" ]]; then | |
| REPORTS_FOLDER=$2 | |
| fi | |
| if [[ $3 != "" ]]; then | |
| HELP_FOLDER=$3 | |
| fi | |
| #4. Generate the file names based on the folder names. | |
| TOOLS_FOLDER_CREATED=".$TOOLS_FOLDER-FolderCreated" | |
| REPORTS_FOLDER_CREATED=".$REPORTS_FOLDER-FolderCreated" | |
| HELP_FOLDER_CREATED=".$HELP_FOLDER-FolderCreated" | |
| TODAY=$(date) | |
| PATH_TO_LOG="$HOME/Library/Logs/folderCreator_log_v1-3.log" | |
| echo "$(date) Starting" >> $PATH_TO_LOG | |
| #5. Go to the home folder. | |
| cd $HOME | |
| #6. Check to see if each of the folders exists. If it exists then do not create it. Else create the folder. | |
| echo "$(date) Creating folders: $TOOLS_FOLDER, $REPORTS_FOLDER, $HELP_FOLDER" >> $PATH_TO_LOG | |
| if [[ -d $TOOLS_FOLDER ]]; then | |
| echo "$(date) Not creating $TOOLS_FOLDER as it already exists." >> $PATH_TO_LOG | |
| else | |
| echo "$(date) Creating $TOOLS_FOLDER" >> $PATH_TO_LOG | |
| mkdir $TOOLS_FOLDER | |
| fi | |
| if [[ -d $REPORTS_FOLDER ]]; then | |
| echo "$(date) Not creating $REPORTS_FOLDER as it already exists." >> $PATH_TO_LOG | |
| else | |
| echo "$(date) Creating $REPORTS_FOLDER" >> $PATH_TO_LOG | |
| mkdir $REPORTS_FOLDER | |
| fi | |
| if [[ -d $HELP_FOLDER ]]; then | |
| echo "$(date) Not creating $HELP_FOLDER as it already exists." >> $PATH_TO_LOG | |
| else | |
| echo "$(date) Creating $HELP_FOLDER" >> $PATH_TO_LOG | |
| mkdir $HELP_FOLDER | |
| fi | |
| #7. Create the task completion file inside each folder. | |
| echo "$(date) Creating hidden file for $TOOLS_FOLDER folder." >> $PATH_TO_LOG | |
| cd $TOOLS_FOLDER | |
| touch $TOOLS_FOLDER_CREATED | |
| cd .. | |
| echo "$(date) Creating hidden file for $REPORTS_FOLDER folder." >> $PATH_TO_LOG | |
| cd $REPORTS_FOLDER | |
| touch $REPORTS_FOLDER_CREATED | |
| cd .. | |
| echo "$(date) Creating hidden file for $HELP_FOLDER folder." >> $PATH_TO_LOG | |
| cd $HELP_FOLDER | |
| touch $HELP_FOLDER_CREATED | |
| cd .. | |
| echo "$(date) Task completed. Have a nice day!" | |
| #------------------------------------------------------------------------------------------------- | |
| #------------------------------------------------------------------------------------------------- | |
| #------------------------------------------------------------------------------------------------- | |
| # ------------------------------ END OF SCRIPT --------------------------------------------------- |
Other options
There is one more way of providing information.
- man pages
- Other documents such as: pdf, txt…
- Web based blog: This could be a dedicated page or part of the version control tool page.
- Video based tutorial. This is used in cases where the script has a lot of capabilities and is used very often.
In fact, our blog has made use of the GitHub webpage all this while. To this we have added documentation and help tools too.
Downloads
You can download the completed file from here. You can download a template for the documentation from here.
Arun Patwardhan's Blog 
Pingback: Shell scripting in macOS – Part 5: Loops | Arun Patwardhan's Blog
Pingback: Shell scripting in macOS – Part 1 | Arun Patwardhan's Blog