Deployed f43708e to git-main with MkDocs 1.6.0 and mike 2.1.2

git-main/developer-guide/style-guide/index.html

@@ -798,15 +798,6 @@
     </span>
   </a>
 
-</li>
-
-          <li class="md-nav__item">
-  <a href="#function-arguments" class="md-nav__link">
-    <span class="md-ellipsis">
-      Function Arguments
-    </span>
-  </a>
-
 </li>
 
           <li class="md-nav__item">
@@ -1477,15 +1468,6 @@
     </span>
   </a>
 
-</li>
-
-          <li class="md-nav__item">
-  <a href="#function-arguments" class="md-nav__link">
-    <span class="md-ellipsis">
-      Function Arguments
-    </span>
-  </a>
-
 </li>
 
           <li class="md-nav__item">
@@ -1571,49 +1553,56 @@
 
 
 <h1 id="style-guide">Style Guide<a class="headerlink" href="#style-guide" title="Permanent link">&para;</a></h1>
-<p>The focus of anyone contributing to this project should be to write code that is easily understood by anyone, including people who have little experience with ROSflight or coding in general. So, we ask that contributions adhere to the following style guidelines.</p>
+<p>The focus of anyone contributing to this project should be to write code that is easily understood by anyone, including people who have little experience with ROSflight or coding in general.
+So, we ask that contributions adhere to the following style guidelines.</p>
 <h2 id="comments">Comments<a class="headerlink" href="#comments" title="Permanent link">&para;</a></h2>
-<p>Well written and clear code should be easy to understand even without comments. However, since this project is intended to be as accessible as possible, we ask that you write both clear code and clear comments. Don't use comments to explain code that would be difficult to understand without comments, but instead use them to make clear code even more understandable.</p>
+<p>Well written and clear code should be easy to understand even without comments.
+However, since this project is intended to be as accessible as possible, we ask that you write both clear code and clear comments.
+Don't use comments to explain code that would be difficult to understand without comments, but instead use them to make clear code even more understandable.</p>
 <h3 id="doxygen">Doxygen<a class="headerlink" href="#doxygen" title="Permanent link">&para;</a></h3>
-<p>Doxygen comments should be added pretty much anywhere where it makes sense. Please include at least a brief for anything you write. For methods and functions, also include explanations of all arguments and the return value. More detailed explanations are encouraged for non-trivial methods and objects.</p>
+<p>Doxygen comments should be added pretty much anywhere where it makes sense.
+Please include at least a brief for anything you write.
+For methods and functions, also include explanations of all arguments and the return value.
+See the below example for the Doxygen style you should use.
+<div class="highlight"><pre><span></span><code><span class="cm">/**</span>
+<span class="cm">  * @brief Converts an LLA coordinate to NED coordinates</span>
+<span class="cm">  * </span>
+<span class="cm">  * @param lla: Array of floats of size 3, with [latitude, longitude, altitude]</span>
+<span class="cm">  * @return Array of doubles corresponding to the NED coordinates measured from the origin</span>
+<span class="cm">  */</span>
+<span class="n">std</span><span class="o">::</span><span class="n">array</span><span class="o">&lt;</span><span class="kt">double</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="o">&gt;</span><span class="w"> </span><span class="n">lla2ned</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">array</span><span class="o">&lt;</span><span class="kt">float</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="o">&gt;</span><span class="w"> </span><span class="n">lla</span><span class="p">);</span>
+</code></pre></div></p>
+<p>More detailed explanations are encouraged for non-trivial methods and objects.
+For single-line Doxygen comments, three slashes is acceptable, e.g., <code>/// Comment here</code>.</p>
 <h2 id="white-space-and-line-endings">White Space and Line Endings<a class="headerlink" href="#white-space-and-line-endings" title="Permanent link">&para;</a></h2>
-<p>Please try not to commit anything that only changes white space or line endings. To check if that's going to happen, run <code>git diff --check</code> before you stage your files.</p>
+<p>Please try not to commit anything that only changes white space or line endings.
+To check if that's going to happen, run <code>git diff --check</code> before you stage your files.</p>
 <h2 id="code-style">Code Style<a class="headerlink" href="#code-style" title="Permanent link">&para;</a></h2>
-<p>ROSflight follows the <a href="https://docs.ros.org/en/humble/The-ROS2-Project/Contributing/Code-Style-Language-Versions.html">ROS2 C++ style guide</a>, with some more specific guidelines below. Please follow first the style guidelines below and then the ROS2 guidelines. A .clang-format file and format-correcting script is provided in most ROSflight repositories that can be used to auto-format your code to help you find things you might have missed. Format checks on pull requests using this .clang-format file may also exist.</p>
+<p>ROSflight follows the <a href="https://docs.ros.org/en/humble/The-ROS2-Project/Contributing/Code-Style-Language-Versions.html">ROS2 C++ style guide</a>, with some more specific guidelines below.
+Please follow first the style guidelines below and then the ROS2 guidelines.
+A .clang-format file and format-correcting script is provided in most ROSflight repositories that can be used to auto-format your code to help you find things you might have missed.</p>
 <h3 id="indentation">Indentation<a class="headerlink" href="#indentation" title="Permanent link">&para;</a></h3>
-<p>Indentation should be <strong>2 spaces</strong> (no tabs). Case statements in switch blocks should not be indented, e.g.</p>
-<div class="highlight"><pre><span></span><code><span class="k">switch</span><span class="w"> </span><span class="p">(</span><span class="n">variable</span><span class="p">)</span>
-<span class="p">{</span>
-<span class="k">case</span><span class="w"> </span><span class="mi">1</span><span class="p">:</span>
-<span class="w">  </span><span class="c1">// do something</span>
-<span class="w">  </span><span class="k">break</span><span class="p">;</span>
-<span class="k">default</span><span class="o">:</span>
-<span class="w">  </span><span class="k">break</span><span class="p">;</span>
-<span class="p">}</span>
-</code></pre></div>
+<p>Indentation should be <strong>2 spaces</strong> (no tabs).</p>
 <h3 id="spaces">Spaces<a class="headerlink" href="#spaces" title="Permanent link">&para;</a></h3>
-<p>There should be a space between <code>if</code>, <code>for</code>, or <code>while</code> and the condition, e.g. <code>while (true)</code>, not <code>while(true)</code>.</p>
+<p>There should be a space between <code>if</code>, <code>for</code>, or <code>while</code> and the condition.
+<div class="highlight"><pre><span></span><code><span class="c1">// Correct</span>
+<span class="k">while</span><span class="w"> </span><span class="p">(</span><span class="nb">true</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="p">}</span>
+
+<span class="c1">// Incorrect</span>
+<span class="k">while</span><span class="p">(</span><span class="nb">true</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="p">}</span>
+</code></pre></div></p>
 <h3 id="naming-conventions">Naming Conventions<a class="headerlink" href="#naming-conventions" title="Permanent link">&para;</a></h3>
 <ul>
-<li>Class names should be capitalized with no spaces (i.e. <code>StateManager</code>).</li>
+<li>Class names should be CamelCase, that is, capitalized with no spaces (i.e. <code>StateManager</code>).</li>
 <li>Member variables should contain a post-pended underscore (i.e. <code>data_</code>).</li>
 <li>Member functions should be all lower case with underscores (i.e. <code>set_error()</code>).</li>
 <li>Boolean values should be assigned <code>true</code> or <code>false</code>, not <code>0</code> or <code>1</code>.</li>
 </ul>
-<h3 id="function-arguments">Function Arguments<a class="headerlink" href="#function-arguments" title="Permanent link">&para;</a></h3>
-<p>Primitive data types (<code>int</code>, <code>float</code>, etc.) should always be passed by value. Other types (e.g. classes) should be passed by reference and should maintain proper const-correctness. Arguments that are modified by the function should be passed by pointer instead of reference, to make the fact that the argument will be changed clearer in the calling code. For example:</p>
-<div class="highlight"><pre><span></span><code><span class="kt">void</span><span class="w"> </span><span class="nf">do_something</span><span class="p">(</span><span class="kt">float</span><span class="w"> </span><span class="n">dt</span><span class="p">,</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="n">MyClass</span><span class="o">&amp;</span><span class="w"> </span><span class="n">data</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="o">*</span><span class="w"> </span><span class="n">output</span><span class="p">);</span>
-</code></pre></div>
-<p>This function would be called as</p>
-<div class="highlight"><pre><span></span><code><span class="kt">float</span><span class="w"> </span><span class="n">dt</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">0.01f</span><span class="p">;</span>
-<span class="n">MyClass</span><span class="w"> </span><span class="n">my_class</span><span class="p">;</span>
-<span class="kt">int</span><span class="w"> </span><span class="n">value</span><span class="p">;</span>
-
-<span class="n">do_something</span><span class="p">(</span><span class="n">dt</span><span class="p">,</span><span class="w"> </span><span class="n">my_class</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">value</span><span class="p">);</span>
-</code></pre></div>
-<p>This makes it clear the <code>value</code> is modified by the function call.</p>
 <h3 id="classes">Classes<a class="headerlink" href="#classes" title="Permanent link">&para;</a></h3>
-<p>All modules should be defined as a self-contained class. All member variables should be declared as "private," named with a post-pended underscore, and accessed through inline accessor functions. All accessible data should be encapsulated in a struct. For example, here is a snippet from the <code>Sensors</code> module in the firmware:</p>
+<p>All modules should be defined as a self-contained class.
+All member variables should be declared as "private," named with a post-pended underscore.
+All accessible data should be encapsulated in a struct.
+For example, here is a snippet from the <code>Sensors</code> module in the firmware:</p>
 <div class="highlight"><pre><span></span><code><span class="k">class</span><span class="w"> </span><span class="nc">Sensors</span>
 <span class="p">{</span>
 <span class="k">public</span><span class="o">:</span>
@@ -1653,7 +1642,7 @@ <h3 id="classes">Classes<a class="headerlink" href="#classes" title="Permanent l
 <span class="w">  </span><span class="n">Data</span><span class="w"> </span><span class="n">data_</span><span class="p">;</span>
 <span class="p">}</span>
 </code></pre></div>
-<p>Note that <code>data_</code> is a private member variable, but the <code>Data</code> struct is declared publicly and <code>data_</code> is accessed through an <code>inline const</code> accessor to prevent another module from changing <code>data_</code>.</p>
+<p>Note that <code>data_</code> is a private member variable, but the <code>Data</code> struct is declared publicly.</p>
 <h3 id="enums">Enums<a class="headerlink" href="#enums" title="Permanent link">&para;</a></h3>
 <p>Enums should be declared using the following style:
 <div class="highlight"><pre><span></span><code><span class="k">enum</span><span class="w"> </span><span class="nc">ArmedState</span>
@@ -1674,7 +1663,8 @@ <h3 id="structs">Structs<a class="headerlink" href="#structs" title="Permanent l
 </code></pre></div>
 Struct type names should be in CamelCase.</p>
 <h3 id="globals">Globals<a class="headerlink" href="#globals" title="Permanent link">&para;</a></h3>
-<p>The use of global variables should be limited to when absolutely necessary (such as linking to interrupt routines or hardware peripherals). This should only occur in board support layers and not in the core ROSflight libary code.</p>
+<p>The use of global variables should be limited to when absolutely necessary (such as linking to interrupt routines or hardware peripherals).
+This should only occur in board support layers and not in the core ROSflight libary code, ROSplane, or ROScopter.</p>
 <h3 id="include-order">Include Order<a class="headerlink" href="#include-order" title="Permanent link">&para;</a></h3>
 <p>Include files at the top of your file in the following order:</p>
 <ol>
@@ -1683,8 +1673,13 @@ <h3 id="include-order">Include Order<a class="headerlink" href="#include-order"
 <li>Other header files from this project (e.g. <code>"rosflight.h"</code>)</li>
 <li>The header file for this specific source file</li>
 </ol>
-<p>Group the includes according to the above list with an empty line between each group. (For external libraries, you may subdivide group 2 into a group for each library.) The first two groups should use angle brackets (<code>&lt;&gt;</code>), and the last two groups should use quotation marks (<code>""</code>). Files from external libraries should be namespaced by the library name (e.g. <code>&lt;breezystm32/breezystm32.h&gt;</code>, not <code>&lt;breezystm32.h&gt;</code>).</p>
-<p>Alphabetize the files within each group. Do not change the include order to fix build errors; if you have to do that it means you are not including a file somewhere that you should. Please fix it by including all the right files.</p>
+<p>Group the includes according to the above list with an empty line between each group.
+(For external libraries, you may subdivide group 2 into a group for each library.)
+The first two groups should use angle brackets (<code>&lt;&gt;</code>), and the last two groups should use quotation marks (<code>""</code>).
+Files from external libraries should be namespaced by the library name (e.g. <code>&lt;breezystm32/breezystm32.h&gt;</code>, not <code>&lt;breezystm32.h&gt;</code>).</p>
+<p>Alphabetize the files within each group.
+Do not change the include order to fix build errors; if you have to do that it means you are not including a file somewhere that you should.
+Please fix it by including all the right files.</p>
 <p>Include C standard library headers using the C++ style (<code>#include &lt;cmath&gt;</code>) instead of the C style (<code>#include &lt;math.h&gt;</code>).</p>
 <p>For example, in <code>sensors.c</code> I might have:
 <div class="highlight"><pre><span></span><code><span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;cstdbool&gt;</span>