documentation/in-progress/shelldocs/index.html - yetus - Git at Google

 <!---
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.
 -->

 <html>
     <head>
         <meta charset="utf-8">
         <title>Apache Yetus</title>
         <meta name="viewport" content="width=device-width, initial-scale=1.0">
         <meta name="description" content="">
         <meta name="author" content="">

         <link href="../../../assets/css/bootstrap.css" rel="stylesheet">
         <link href="../../../assets/css/bootstrap-theme.css" rel="stylesheet">
         <link href="../../../assets/css/font-awesome.css" rel="stylesheet">

         <!-- JS -->
         <script type="text/javascript" src="../../../assets/js/jquery-2.1.4.min.js"></script>
         <script type="text/javascript" src="../../../assets/js/bootstrap.js"></script>
   </head>
     <body>

 <div class="navbar navbar-inverse navbar-static-top" role="navigation">
     <div class="container">
         <div class="navbar-header">
             <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
                 <span class="sr-only">Toggle navigation</span>
                 <span class="icon-bar"></span>
                 <span class="icon-bar"></span>
                 <span class="icon-bar"></span>
             </button>
             <a class="img-responsive pull-left" href="/">
                 <img style="max-height: 40px; margin-top: 5px; margin-bottom: 5px;" src="../../../assets/img/yetus_logo.png" alt="Apache Yetus logo" />
             </a>
         </div>
         <div class="navbar-collapse collapse">
             <ul class="nav navbar-nav">
                 <li><a href="/downloads/">Downloads</a>
                 <li class="dropdown">
                     <a class="dropdown-toggle" data-toggle="dropdown" href="#">Documentation <span class="caret"></span></a>
                     <ul class="dropdown-menu" role="menu">
                       <li><a href="/documentation/0.13.0/">Docs for v0.13.0</a></li>
                       <li><a href="/documentation/0.14.1/">Docs for v0.14.1</a></li>
                       <li><a href="/documentation/0.15.0/">Docs for v0.15.0</a></li>
                       <li><a href="/documentation/in-progress/">In Progress Docs for Contributors</a>
                       </li>
                       <li><a href="/documentation/history/">History of the Project</a>
                       </li>
                     </ul>
                 </li>
                 <li class="dropdown">
                     <a class="dropdown-toggle" data-toggle="dropdown" href="#">Get Involved <span class="caret"></span></a>
                     <ul class="dropdown-menu" role="menu" aria-labelledby="drop1">
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="/mailinglists"><i class="fa fa-commenting"></i> Mailing Lists</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="https://issues.apache.org/jira/browse/YETUS"><i class="fa fa-bug"></i> JIRA (Bugs)</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="https://gitbox.apache.org/repos/asf/yetus.git"><i class="fa fa-code"></i> Source (Apache)</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="https://github.com/apache/yetus"><i class="fa fa-github-alt"></i> Source (GitHub)</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="/contribute/"><i class="fa fa-code-fork"></i> Contributing</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="https://twitter.com/ApacheYetus"><i class="fa fa-twitter"></i> @ApacheYetus</a>
                         </li>
                     </ul>
                 </li>
                 <li>
                     <li class="dropdown">
                         <a class="dropdown-toggle" data-toggle="dropdown" href="#">Apache Software Foundation <b class="caret"></b></a>
                         <ul class="dropdown-menu" role="menu">
                             <li><a href="https://www.apache.org">Apache Homepage</a>
                             </li>
                             <li><a href="https://www.apache.org/licenses/">Apache License</a>
                             </li>
                             <li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a>
                             </li>
                             <li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a>
                             </li>
                             <li><a href="https://www.apache.org/security/">Security</a>
                             </li>
                         </ul>
                     </li>
                 </li>
             </ul>
         </div>
         <!--/.nav-collapse -->
     </div>
 </div>

       <div class="container">
         <!---
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.
 -->

 <h1 id="shelldocs">shelldocs</h1>

 <!-- MarkdownTOC levels="1,2" autolink="true" indent="  " bullets="*" bracket="round" -->

 <ul>
   <li><a href="#purpose">Purpose</a></li>
   <li><a href="#requirements">Requirements</a></li>
   <li><a href="#function-annotations">Function Annotations</a>
     <ul>
       <li><a href="#audience--stability">Audience / Stability</a></li>
       <li><a href="#multiple-parameters">Multiple Parameters</a></li>
       <li><a href="#return-values">Return Values</a></li>
       <li><a href="#code-example">Code Example</a></li>
     </ul>
   </li>
   <li><a href="#basic-usage">Basic Usage</a></li>
   <li><a href="#skipping-files">Skipping Files</a></li>
   <li><a href="#avoiding-private-or-non-replaceable-functions">Avoiding Private or Non-Replaceable Functions</a></li>
   <li><a href="#lint-mode">Lint Mode</a></li>
 </ul>

 <!-- /MarkdownTOC -->

 <h1 id="purpose">Purpose</h1>

 <p>Some projects have complex shell functions that act as APIs. <code>shelldocs</code> provides an annotation system similar to JavaDoc. It allows a developer to auto-generate MultiMarkdown documentation files as input to other processing systems.</p>

 <h1 id="requirements">Requirements</h1>

 <ul>
   <li>Python 3.8</li>
 </ul>

 <h1 id="function-annotations">Function Annotations</h1>

 <p><code>shelldocs</code> works by doing simple parsing of shell scripts.  As such, it looks for code that matches these patterns:</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="c">## @annotation</span>
 <span class="k">function </span>functioname<span class="o">()</span> <span class="o">{</span>
   ...
 <span class="o">}</span>
 </code></pre></div>
 <div class="highlight"><pre class="highlight shell"><code><span class="c">## @annotation</span>
 <span class="k">function </span>functioname <span class="o">()</span> <span class="o">{</span>
   ...
 <span class="o">}</span>
 </code></pre></div>
 <div class="highlight"><pre class="highlight shell"><code><span class="c">## @annotation</span>
 <span class="k">function </span>functioname <span class="o">{</span>
   ...
 <span class="o">}</span>
 </code></pre></div>
 <div class="highlight"><pre class="highlight shell"><code><span class="c">## @annotation</span>
 <span class="k">function </span>functioname
 <span class="o">{</span>
   ...
 <span class="o">}</span>
 </code></pre></div>
 <div class="highlight"><pre class="highlight shell"><code><span class="c">## @annotation</span>
 functioname<span class="o">()</span> <span class="o">{</span>
   ...
 <span class="o">}</span>
 </code></pre></div>
 <div class="highlight"><pre class="highlight shell"><code><span class="c">## @annotation</span>
 functioname <span class="o">()</span> <span class="o">{</span>
   ...
 <span class="o">}</span>
 </code></pre></div>
 <p>Note that the comment has two hash ('#') marks.  The content of the comment is key.  This is what <code>shelldocs</code> will turn into documentation.  The following annotations are supported:</p>

 <table class="table table-bordered table-striped">
   <thead>
     <tr>
       <th style="text-align: left">Annotation</th>
       <th style="text-align: left">Required</th>
       <th style="text-align: left">Description</th>
       <th style="text-align: left">Acceptable Values</th>
       <th style="text-align: left">Default</th>
     </tr>
   </thead>
   <tbody>
     <tr>
       <td style="text-align: left">@description</td>
       <td style="text-align: left">No</td>
       <td style="text-align: left">What this function does, intended purpose, etc.</td>
       <td style="text-align: left">text</td>
       <td style="text-align: left">None</td>
     </tr>
     <tr>
       <td style="text-align: left">@audience</td>
       <td style="text-align: left">Yes</td>
       <td style="text-align: left">Who should use this function?</td>
       <td style="text-align: left">public, private,</td>
       <td style="text-align: left">None</td>
     </tr>
     <tr>
       <td style="text-align: left">@stability</td>
       <td style="text-align: left">Yes</td>
       <td style="text-align: left">Is this function going to change?</td>
       <td style="text-align: left">stable, evolving</td>
       <td style="text-align: left">None</td>
     </tr>
     <tr>
       <td style="text-align: left">@replaceable</td>
       <td style="text-align: left">No</td>
       <td style="text-align: left">Is this function safely 'monkeypatched'?</td>
       <td style="text-align: left">yes or no</td>
       <td style="text-align: left">No</td>
     </tr>
     <tr>
       <td style="text-align: left">@param</td>
       <td style="text-align: left">No</td>
       <td style="text-align: left">A single parameter</td>
       <td style="text-align: left">A single keyword. e.g., 'seconds' to specify that this function requires a time in seconds</td>
       <td style="text-align: left">None</td>
     </tr>
     <tr>
       <td style="text-align: left">@return</td>
       <td style="text-align: left">No</td>
       <td style="text-align: left">What does this function return?</td>
       <td style="text-align: left">text</td>
       <td style="text-align: left">Nothing</td>
     </tr>
   </tbody>
 </table>

 <h2 id="audience--stability">Audience / Stability</h2>

 <p>This values are the shell equivalents to the Java versions present in Apache Yetus Audience Annotations.</p>

 <h2 id="multiple-parameters">Multiple Parameters</h2>

 <p>Each parameter requires it's own <code>@param</code> line and they must be listed in order.</p>

 <h2 id="return-values">Return Values</h2>

 <p>It is recommended that multiple <code>@return</code> entries should be used when multiple values are possible.  For example:</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="c">## @return 0 - success</span>
 <span class="c">## @return 1 - failure</span>
 </code></pre></div>
 <h2 id="code-example">Code Example</h2>

 <div class="highlight"><pre class="highlight shell"><code><span class="c">## @description This is an example</span>
 <span class="c">## @description of what one can do.</span>
 <span class="c">## @audience public</span>
 <span class="c">## @stability stable</span>
 <span class="c">## @param integer</span>
 <span class="c">## @param integer</span>
 <span class="c">## @return sum</span>
 <span class="k">function </span>add_two_numbers<span class="o">()</span> <span class="o">{</span>
   <span class="k">return</span> <span class="o">((</span><span class="nv">$1</span> + <span class="nv">$2</span><span class="o">))</span>
 <span class="o">}</span>
 </code></pre></div>
 <h1 id="basic-usage">Basic Usage</h1>

 <p>The <code>shelldocs</code> executable requires at least one input file and either an output file or to run in lint mode.  Lint mode is covered below.</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>shelldocs <span class="nt">--output</span> functions.md <span class="nt">--input</span> myshelldirectory
 </code></pre></div>
 <p>This will process all of the files in <code>myshelldirectory</code> that end in <code>sh</code> and generate an output file called <code>functions.md</code>.  This file will contain a table of contents of all of the functions arranged by audience, stability, and replace-ability.</p>

 <h1 id="skipping-files">Skipping Files</h1>

 <p>When processing directories, it may be desirable to avoid certain files. This may be done by including a comment in the file:</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="c"># SHELLDOC-IGNORE</span>
 </code></pre></div>
 <p>This comment tells <code>shelldocs</code> that this file should not be processed.</p>

 <h1 id="avoiding-private-or-non-replaceable-functions">Avoiding Private or Non-Replaceable Functions</h1>

 <p>Some functions are not meant to be used by 3rd parties or cannot be easily replaced.  These functions may be omitted from the documentation by using the <code>--skipprnorep</code> flag:</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>shelldocs <span class="nt">--skipprnorep</span> <span class="nt">--input</span> directory <span class="nt">--output</span> file.md
 </code></pre></div>
 <h1 id="lint-mode">Lint Mode</h1>

 <p>In order to ensure minimal documentation, <code>shelldocs</code> has a <code>--lint</code> mode that will point out functions that are missing required annotations:</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>shelldocs <span class="nt">--input</span> directory <span class="nt">--lint</span>
 </code></pre></div>
 <p>This will process <code>directory</code> and inform the user of any such problems.</p>

     </div>

 <div class="container">
     <hr>
     <footer class="footer">
         <div class="row-fluid">
             <div class="span12 text-left">
               <div class="span12">
                 Copyright 2008-2023 <a href="https://www.apache.org/">Apache Software Foundation</a>. Licensed under the <a href="https://www.apache.org/licenses/">Apache License v2.0</a>. Apache Yetus and the Apache feather logo are trademarks of The Apache Software Foundation.
               </div>
             </div>

         </div>

     </footer>
 </div>

   </body>
 </html>
	<!---
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	<html>
	<head>
	<meta charset="utf-8">
	<title>Apache Yetus</title>
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<meta name="description" content="">
	<meta name="author" content="">

	<link href="../../../assets/css/bootstrap.css" rel="stylesheet">
	<link href="../../../assets/css/bootstrap-theme.css" rel="stylesheet">
	<link href="../../../assets/css/font-awesome.css" rel="stylesheet">

	<!-- JS -->
	<script type="text/javascript" src="../../../assets/js/jquery-2.1.4.min.js"></script>
	<script type="text/javascript" src="../../../assets/js/bootstrap.js"></script>
	</head>
	<body>

	<div class="navbar navbar-inverse navbar-static-top" role="navigation">
	<div class="container">
	<div class="navbar-header">
	<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
	<span class="sr-only">Toggle navigation</span>
	<span class="icon-bar"></span>
	<span class="icon-bar"></span>
	<span class="icon-bar"></span>
	</button>
	<a class="img-responsive pull-left" href="/">
	<img style="max-height: 40px; margin-top: 5px; margin-bottom: 5px;" src="../../../assets/img/yetus_logo.png" alt="Apache Yetus logo" />
	</a>
	</div>
	<div class="navbar-collapse collapse">
	<ul class="nav navbar-nav">
	<li><a href="/downloads/">Downloads</a>
	<li class="dropdown">
	<a class="dropdown-toggle" data-toggle="dropdown" href="#">Documentation <span class="caret"></span></a>
	<ul class="dropdown-menu" role="menu">
	<li><a href="/documentation/0.13.0/">Docs for v0.13.0</a></li>
	<li><a href="/documentation/0.14.1/">Docs for v0.14.1</a></li>
	<li><a href="/documentation/0.15.0/">Docs for v0.15.0</a></li>
	<li><a href="/documentation/in-progress/">In Progress Docs for Contributors</a>
	</li>
	<li><a href="/documentation/history/">History of the Project</a>
	</li>
	</ul>
	</li>
	<li class="dropdown">
	<a class="dropdown-toggle" data-toggle="dropdown" href="#">Get Involved <span class="caret"></span></a>
	<ul class="dropdown-menu" role="menu" aria-labelledby="drop1">
	<li role="presentation"><a role="menuitem" tabindex="-1" href="/mailinglists"><i class="fa fa-commenting"></i> Mailing Lists</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="https://issues.apache.org/jira/browse/YETUS"><i class="fa fa-bug"></i> JIRA (Bugs)</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="https://gitbox.apache.org/repos/asf/yetus.git"><i class="fa fa-code"></i> Source (Apache)</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="https://github.com/apache/yetus"><i class="fa fa-github-alt"></i> Source (GitHub)</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="/contribute/"><i class="fa fa-code-fork"></i> Contributing</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="https://twitter.com/ApacheYetus"><i class="fa fa-twitter"></i> @ApacheYetus</a>
	</li>
	</ul>
	</li>
	<li>
	<li class="dropdown">
	<a class="dropdown-toggle" data-toggle="dropdown" href="#">Apache Software Foundation <b class="caret"></b></a>
	<ul class="dropdown-menu" role="menu">
	<li><a href="https://www.apache.org">Apache Homepage</a>
	</li>
	<li><a href="https://www.apache.org/licenses/">Apache License</a>
	</li>
	<li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a>
	</li>
	<li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a>
	</li>
	<li><a href="https://www.apache.org/security/">Security</a>
	</li>
	</ul>
	</li>
	</li>
	</ul>
	</div>
	<!--/.nav-collapse -->
	</div>
	</div>

	<div class="container">
	<!---
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	<h1 id="shelldocs">shelldocs</h1>

	<!-- MarkdownTOC levels="1,2" autolink="true" indent=" " bullets="*" bracket="round" -->

	<ul>
	<li><a href="#purpose">Purpose</a></li>
	<li><a href="#requirements">Requirements</a></li>
	<li><a href="#function-annotations">Function Annotations</a>
	<ul>
	<li><a href="#audience--stability">Audience / Stability</a></li>
	<li><a href="#multiple-parameters">Multiple Parameters</a></li>
	<li><a href="#return-values">Return Values</a></li>
	<li><a href="#code-example">Code Example</a></li>
	</ul>
	</li>
	<li><a href="#basic-usage">Basic Usage</a></li>
	<li><a href="#skipping-files">Skipping Files</a></li>
	<li><a href="#avoiding-private-or-non-replaceable-functions">Avoiding Private or Non-Replaceable Functions</a></li>
	<li><a href="#lint-mode">Lint Mode</a></li>
	</ul>

	<!-- /MarkdownTOC -->

	<h1 id="purpose">Purpose</h1>

	<p>Some projects have complex shell functions that act as APIs. <code>shelldocs</code> provides an annotation system similar to JavaDoc. It allows a developer to auto-generate MultiMarkdown documentation files as input to other processing systems.</p>

	<h1 id="requirements">Requirements</h1>

	<ul>
	<li>Python 3.8</li>
	</ul>

	<h1 id="function-annotations">Function Annotations</h1>

	<p><code>shelldocs</code> works by doing simple parsing of shell scripts. As such, it looks for code that matches these patterns:</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="c">## @annotation</span>
	<span class="k">function </span>functioname<span class="o">()</span> <span class="o">{</span>
	...
	<span class="o">}</span>
	</code></pre></div>
	<div class="highlight"><pre class="highlight shell"><code><span class="c">## @annotation</span>
	<span class="k">function </span>functioname <span class="o">()</span> <span class="o">{</span>
	...
	<span class="o">}</span>
	</code></pre></div>
	<div class="highlight"><pre class="highlight shell"><code><span class="c">## @annotation</span>
	<span class="k">function </span>functioname <span class="o">{</span>
	...
	<span class="o">}</span>
	</code></pre></div>
	<div class="highlight"><pre class="highlight shell"><code><span class="c">## @annotation</span>
	<span class="k">function </span>functioname
	<span class="o">{</span>
	...
	<span class="o">}</span>
	</code></pre></div>
	<div class="highlight"><pre class="highlight shell"><code><span class="c">## @annotation</span>
	functioname<span class="o">()</span> <span class="o">{</span>
	...
	<span class="o">}</span>
	</code></pre></div>
	<div class="highlight"><pre class="highlight shell"><code><span class="c">## @annotation</span>
	functioname <span class="o">()</span> <span class="o">{</span>
	...
	<span class="o">}</span>
	</code></pre></div>
	<p>Note that the comment has two hash ('#') marks. The content of the comment is key. This is what <code>shelldocs</code> will turn into documentation. The following annotations are supported:</p>

	<table class="table table-bordered table-striped">
	<thead>
	<tr>
	<th style="text-align: left">Annotation</th>
	<th style="text-align: left">Required</th>
	<th style="text-align: left">Description</th>
	<th style="text-align: left">Acceptable Values</th>
	<th style="text-align: left">Default</th>
	</tr>
	</thead>
	<tbody>
	<tr>
	<td style="text-align: left">@description</td>
	<td style="text-align: left">No</td>
	<td style="text-align: left">What this function does, intended purpose, etc.</td>
	<td style="text-align: left">text</td>
	<td style="text-align: left">None</td>
	</tr>
	<tr>
	<td style="text-align: left">@audience</td>
	<td style="text-align: left">Yes</td>
	<td style="text-align: left">Who should use this function?</td>
	<td style="text-align: left">public, private,</td>
	<td style="text-align: left">None</td>
	</tr>
	<tr>
	<td style="text-align: left">@stability</td>
	<td style="text-align: left">Yes</td>
	<td style="text-align: left">Is this function going to change?</td>
	<td style="text-align: left">stable, evolving</td>
	<td style="text-align: left">None</td>
	</tr>
	<tr>
	<td style="text-align: left">@replaceable</td>
	<td style="text-align: left">No</td>
	<td style="text-align: left">Is this function safely 'monkeypatched'?</td>
	<td style="text-align: left">yes or no</td>
	<td style="text-align: left">No</td>
	</tr>
	<tr>
	<td style="text-align: left">@param</td>
	<td style="text-align: left">No</td>
	<td style="text-align: left">A single parameter</td>
	<td style="text-align: left">A single keyword. e.g., 'seconds' to specify that this function requires a time in seconds</td>
	<td style="text-align: left">None</td>
	</tr>
	<tr>
	<td style="text-align: left">@return</td>
	<td style="text-align: left">No</td>
	<td style="text-align: left">What does this function return?</td>
	<td style="text-align: left">text</td>
	<td style="text-align: left">Nothing</td>
	</tr>
	</tbody>
	</table>

	<h2 id="audience--stability">Audience / Stability</h2>

	<p>This values are the shell equivalents to the Java versions present in Apache Yetus Audience Annotations.</p>

	<h2 id="multiple-parameters">Multiple Parameters</h2>

	<p>Each parameter requires it's own <code>@param</code> line and they must be listed in order.</p>

	<h2 id="return-values">Return Values</h2>

	<p>It is recommended that multiple <code>@return</code> entries should be used when multiple values are possible. For example:</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="c">## @return 0 - success</span>
	<span class="c">## @return 1 - failure</span>
	</code></pre></div>
	<h2 id="code-example">Code Example</h2>

	<div class="highlight"><pre class="highlight shell"><code><span class="c">## @description This is an example</span>
	<span class="c">## @description of what one can do.</span>
	<span class="c">## @audience public</span>
	<span class="c">## @stability stable</span>
	<span class="c">## @param integer</span>
	<span class="c">## @param integer</span>
	<span class="c">## @return sum</span>
	<span class="k">function </span>add_two_numbers<span class="o">()</span> <span class="o">{</span>
	<span class="k">return</span> <span class="o">((</span><span class="nv">$1</span> + <span class="nv">$2</span><span class="o">))</span>
	<span class="o">}</span>
	</code></pre></div>
	<h1 id="basic-usage">Basic Usage</h1>

	<p>The <code>shelldocs</code> executable requires at least one input file and either an output file or to run in lint mode. Lint mode is covered below.</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>shelldocs <span class="nt">--output</span> functions.md <span class="nt">--input</span> myshelldirectory
	</code></pre></div>
	<p>This will process all of the files in <code>myshelldirectory</code> that end in <code>sh</code> and generate an output file called <code>functions.md</code>. This file will contain a table of contents of all of the functions arranged by audience, stability, and replace-ability.</p>

	<h1 id="skipping-files">Skipping Files</h1>

	<p>When processing directories, it may be desirable to avoid certain files. This may be done by including a comment in the file:</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="c"># SHELLDOC-IGNORE</span>
	</code></pre></div>
	<p>This comment tells <code>shelldocs</code> that this file should not be processed.</p>

	<h1 id="avoiding-private-or-non-replaceable-functions">Avoiding Private or Non-Replaceable Functions</h1>

	<p>Some functions are not meant to be used by 3rd parties or cannot be easily replaced. These functions may be omitted from the documentation by using the <code>--skipprnorep</code> flag:</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>shelldocs <span class="nt">--skipprnorep</span> <span class="nt">--input</span> directory <span class="nt">--output</span> file.md
	</code></pre></div>
	<h1 id="lint-mode">Lint Mode</h1>

	<p>In order to ensure minimal documentation, <code>shelldocs</code> has a <code>--lint</code> mode that will point out functions that are missing required annotations:</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>shelldocs <span class="nt">--input</span> directory <span class="nt">--lint</span>
	</code></pre></div>
	<p>This will process <code>directory</code> and inform the user of any such problems.</p>

	</div>

	<div class="container">
	<hr>
	<footer class="footer">
	<div class="row-fluid">
	<div class="span12 text-left">
	<div class="span12">
	Copyright 2008-2023 <a href="https://www.apache.org/">Apache Software Foundation</a>. Licensed under the <a href="https://www.apache.org/licenses/">Apache License v2.0</a>. Apache Yetus and the Apache feather logo are trademarks of The Apache Software Foundation.
	</div>
	</div>

	</div>

	</footer>
	</div>

	</body>
	</html>