appease the linter with offerings

Author: mjschmidt271

components/eamxx/docs/developer/style/format.md

@@ -52,4 +52,4 @@ The summary is in the main pane of the page with the title
 ***Actions*** link at the top of the E3SM repository page;
 select `eamxx-format` from the ***All workflows*** section of the ***Actions***
 sidebar; then choose the most recent run that is associated with your PR,
-which should be near the top of the list. 
+which should be near the top of the list.

components/eamxx/docs/developer/style/functions.md

@@ -1,66 +1,66 @@
 # Functions and Methods
 
-### Naming
+## Naming
 
-- Please name functions (methods) to be ***descriptive*** and ***verb***_-ish_ so
+- Please name functions (methods) to be ***descriptive*** and ***verb**-ish* so
   that the name describes what the function *does*.
-    - For example, `install_flux_capacitor()` instead of `f_capacitor_method()`
-      or `ifc()`.
-    - To note, if your function cannot be named verb-ishly, that is probably a
-      sign that there is a fundamental issue with your function.
+      - For example, `install_flux_capacitor()` instead of `f_capacitor_method()`
+        or `ifc()`.
+      - To note, if your function cannot be named verb-ishly, that is probably a
+        sign that there is a fundamental issue with your function.
 - In general, functions should use `snake_case` and not contain capitalization,
   unless capitalizing that quantity is a standard convention (e.g.,
   `find_Doc_Brown()`).
 
-### Usage
+## Usage
 
 - In situations where multiple class-member variables are passed as function
   arguments, favor passing the object, rather than the individual variables,
   for the sake of shorter lines and function signatures.
 - As a rule of thumb, developers should prefer passing arguments by reference,
   rather than by value, especially in cases for which the argument is ***large***
   or structurally ***complex***.
-    - E.g., prefer `func(Type &x) { ... }` versus `func(Type x) { ... }`.
-    - This holds true much of the time because passing by value creates a copy
-      of the argument for use by the function, and this increases memory
-      pressure and a resultant performance penalty.
+      - E.g., prefer `func(Type &x) { ... }` versus `func(Type x) { ... }`.
+      - This holds true much of the time because passing by value creates a copy
+        of the argument for use by the function, and this increases memory
+        pressure and a resultant performance penalty.
 - To be more in-depth on the topic, we echo the guidance from the
   [***C++ Core Guidelines***](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-introduction)
   and would encourage the curious to read more deeply on the topic.
 
-    > - For "in" parameters, pass cheaply-copied types by value and others by
-    > reference to `const`.
-    > - For "in-out" parameters, pass by reference to non-`const`.
-    > - For "out" parameters, prefer return values to output parameters.
+      > - For "in" parameters, pass cheaply-copied types by value and others by
+      > reference to `const`.
+      > - For "in-out" parameters, pass by reference to non-`const`.
+      > - For "out" parameters, prefer return values to output parameters.
 
-    - The authors go on to explain that "cheap to copy" includes variables
-      holding 2 or 3 words--for example a double, pointer, or reference.
-    - To illustrate, the below function adheres to the provided guidance.
-    
-    ```c++
-    SmallStruct func(LargeNComplex &notSmall, double forty_two, const int *laser,
-                     const BigStruct &lotsaData) {
+      - The authors go on to explain that "cheap to copy" includes variables
+        holding 2 or 3 words--for example a double, pointer, or reference.
+      - To illustrate, the below function adheres to the provided guidance.
 
-      // SmallStruct object is only assigned-to and then returned, so it is
-      // defined as the return type
-      SmallStruct ans;
-      // forty_two, a scalar double, is considered small and so passed by value
-      ans.val = forty_two;
-      // lotsaData, a BigStruct object, is only accessed and so is
-      // passed by const reference
-      ans.other_val = lotsaData.small_piece;
+      ```c++
+      SmallStruct func(LargeNComplex &notSmall, double forty_two, const int *laser,
+                       const BigStruct &lotsaData) {
 
-      // we pass laser by value and as const because pointers are cheap to copy,
-      // and the value is not changed
-      for (int i = 0; i < forty_two; ++i) {
-        ans.val_vector.push_back(laser[i] + notSmall.epsilon[i]);
-      }
+        // SmallStruct object is only assigned-to and then returned, so it is
+        // defined as the return type
+        SmallStruct ans;
+        // forty_two, a scalar double, is considered small and so passed by value
+        ans.val = forty_two;
+        // lotsaData, a BigStruct object, is only accessed and so is
+        // passed by const reference
+        ans.other_val = lotsaData.small_piece;
+
+        // we pass laser by value and as const because pointers are cheap to copy,
+        // and the value is not changed
+        for (int i = 0; i < forty_two; ++i) {
+          ans.val_vector.push_back(laser[i] + notSmall.epsilon[i]);
+        }
 
-      // notSmall is large and also modified in the function, so we pass by
-      // reference
-      // it is also accessed, above, so it must be an argument and not the
-      // return value
-      notSmall.ans_struct = ans;
-      return ans;
-    }
-    ```
+        // notSmall is large and also modified in the function, so we pass by
+        // reference
+        // it is also accessed, above, so it must be an argument and not the
+        // return value
+        notSmall.ans_struct = ans;
+        return ans;
+      }
+      ```

components/eamxx/docs/developer/style/resources/clang-format_HOWTO.md

@@ -25,11 +25,13 @@ Also, note that the `--style` flag can also fully define the options without
 the configuration file as follows, but this is not recommended as the
 configuration could change before this guide is updated to reflect as such.
 
+<!-- markdownlint-disable MD046 MD013 -->
 ??? Danger "Terminal One-(long-)liner"
 
     ```bash {.copy}
     clang-format [-i] --style="{BasedOnStyle: llvm, ColumnLimit: 100, AlignConsecutiveAssignments: true, AlignConsecutiveBitFields: true, AlignConsecutiveMacros: true, AlignEscapedNewlines: true, AlignTrailingComments: true}" <path/to/c++/source/file(s)>
     ```
+<!-- markdownlint-enable MD046 MD013 -->
 
 ## Installing `clang-format`
 
@@ -39,6 +41,7 @@ building `llvm v14` from scratch.
 If you are a non-admin user of a multi-user cluster, HPC platform, etc., then
 it is likely to be an ***easy*** process, though potentially not immediate.
 
+<!-- markdownlint-disable MD046 -->
 ??? Note "If you require or already have multiple versions of `clang-format` installed"
 
     Note that, depending on your requirements, this could be placed in your shell
@@ -73,24 +76,27 @@ it is likely to be an ***easy*** process, though potentially not immediate.
     $ which clang-format
     /usr/local/bin/clang-format-14
     ```
+<!-- markdownlint-enable MD046 -->
 
 === "Personal Machine"
-    
+
+    <!-- markdownlint-disable MD046 -->
     === "Mac Users (Homebrew Package Manager)"
-    
+
         For Mac users, the [Homebrew](https://brew.sh)
-        package manager (`brew`) is the quickest and most straightforward way to get
-        `clang-format` installed.
-        Since `clang-format` v14 is not available to install directly from Homebrew, we
-        install the entire LLVM package at version 14, and this is as simple as
-        
+        package manager (`brew`) is the quickest and most straightforward way
+        to get `clang-format` installed.
+        Since `clang-format` v14 is not available to install directly from
+        Homebrew, we install the entire LLVM package at version 14, and this
+        is as simple as
+
         ```bash {.copy}
         brew install llvm@14
         ```
-        
+
         It it likely that Homebrew will issue a message about not linking the
         `clang`-related tools by default, so next we add the binary to our `PATH`.
-        
+
         ```bash {.copy}
         $ export PATH="/opt/homebrew/opt/llvm@14/bin/clang-format:$PATH"
         # Note: this is the default location for a recent Mac running Apple silicon.
@@ -99,49 +105,50 @@ it is likely to be an ***easy*** process, though potentially not immediate.
         $ which clang-format
         /opt/homebrew/opt/llvm@14/bin/clang-format
         ```
-        
+
         Note also, that if your system has multiple version of `clang-format` installed,
         it may be preferable to instead set a versioned alias to `clang-format`
         (`clang-format-14`) as in
-        
+
         ```c++
         // create a shell-alias
         alias clang-format-14="/opt/homebrew/opt/llvm@14/bin/clang-format"
         ```
-    
+
     === "Linux Users (Package Manager)"
-    
+
         Given the many flavors of Linux, it is difficult to generalize, but there
         is a high probability the proper version of `clang-format` or `llvm` is
         provided by the built-in package manager.
         The commands will differ based on your Linux distribution, but using the
         Debian/Ubuntu `apt` syntax, it could be accomplished via something like
-        
+
         ```bash {.copy}
         $ apt search clang-format
         [...]
         clang-format-14/...
         $ apt install clang-format-14
         ```
-        
+
     === "Build from Source"
-    
-    If you do not succeed in the above, `clang-format` can also be fully built
-    from the [LLVM Compiler Infrastructure](https://github.com/llvm/llvm-project).
-    It will begin with something like
-    
-    ```bash {.copy}
-    git clone git@github.com:llvm/llvm-project.git
-    git checkout llvmorg-14.0.6 # version tag
-    ```
-    
-    Also, if you only need `clang-format` and not any of the other tooling,
-    it will build faster/smaller if you use the CMake flag
-    `-DLLVM_ENABLE_PROJECTS="clang"` to only build `clang` and it's friends,
-    rather than all of `llvm`.
-    And finally, the README for [LLVM version 14.0.6](https://github.com/llvm/llvm-project/tree/llvmorg-14.0.6)
-    is far more comprehensive that the one for the latest version, and it contains
-    instructions specific to that build.
+
+        If you do not succeed in the above, `clang-format` can also be fully built
+        from the [LLVM Compiler Infrastructure](https://github.com/llvm/llvm-project).
+        It will begin with something like
+
+        ```bash {.copy}
+        git clone git@github.com:llvm/llvm-project.git
+        git checkout llvmorg-14.0.6 # version tag
+        ```
+
+        Also, if you only need `clang-format` and not any of the other tooling,
+        it will build faster/smaller if you use the CMake flag
+        `-DLLVM_ENABLE_PROJECTS="clang"` to only build `clang` and it's friends,
+        rather than all of `llvm`.
+        And finally, the README for [LLVM version 14.0.6](https://github.com/llvm/llvm-project/tree/llvmorg-14.0.6)
+        is far more comprehensive that the one for the latest version, and it contains
+        instructions specific to that build.
+    <!-- markdownlint-enable MD046 -->
 
 === "Multi-user System"
 
@@ -160,6 +167,7 @@ administrator to get an official version installed.[^but-conda]
 
 ---
 
+<!-- markdownlint-disable MD046 -->
 ??? Tip "Unnecessary but Convenient Workflow Customization (`direnv`)"
 
     If you'd like to add a layer of automation/complexity to ensure you only use
@@ -170,10 +178,10 @@ administrator to get an official version installed.[^but-conda]
     environment variables based on `$PWD` using a `.envrc` file.
     As an example, here's my `.envrc` that adds `clang-format v14` to the path
     when I'm working on `EAMxx`.
-    
+
     ```bash {.copy}
     PATH_add /opt/homebrew/opt/llvm@14/bin/clang-format
-    
+
     # also, since I often forget to load a python environment that's required for
     # running ctest, this creates or loads a python 3 virtual environment with numpy
     layout python3
@@ -182,16 +190,17 @@ administrator to get an official version installed.[^but-conda]
     # the front end to avoid pip endlessly reminding you to update
     pip install numpy
     ```
-  
+
     This file can be placed in the top-level `EAMxx` directory, and running
     `direnv allow` enables the functionality.
     Namely, executing `cd EAMxx` loads the defined environment that stays loaded
     in any subdirectories, and resets the standard environment when exiting to a
     directory above/outside of `EAMxx`.
-    
+
     For the `conda` fans, this tool can also be used to auto-load a
     pre-configured `conda` environment since the `.envrc` is essentially a bash
     script with a few bells and whistles tacked on.
+<!-- markdownlint-enable MD046 -->
 
 [^but-conda]: There are rumors of using `conda` creatively to do a user-install,
 but that is not an option we support or suggest.

components/eamxx/docs/developer/style/style.md

@@ -16,24 +16,26 @@ will thank you for it!
 - Please give ***descriptive***, rather than ***terse***, names to your
   variables, functions, classes, etc.
 - Avoid idiosyncratic naming or styling conventions.
-    - If the utility of a style decision would not be immediately apparent to
-      a reasonable developer, please avoid its usage.
+      - If the utility of a style decision would not be immediately apparent to
+        a reasonable developer, please avoid its usage.
 - In the hierarchy of coding concerns, correctness and speed take the top
   tiers, but below that level, please favor readability and clarity over
   space savings, line-breaking, heavy use of arcane language features, etc.
-    - That said, if an arcane language feature ***is*** the correct tool to
-      be used, please do so.
-        - And perhaps add a comment to aid the non-Jedi-Master developers who
-          read the code next. :slightly_smiling_face:
+      - That said, if an arcane language feature ***is*** the correct tool to
+        be used, please do so.
+          - And perhaps add a comment to aid the non-Jedi-Master developers who
+            read the code next. :slightly_smiling_face:
 - With regard to comments, the general wisdom is that the correct amount of
   comments is the amount required to make the code clear and easy to understand.
-    - To quote [Jeff Atwood](https://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/) from his essay about code comments:
+      - To quote
+        [Jeff Atwood](https://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/)
+        from his essay about code comments:
 
       > Only at the point where the code *cannot* be made easier to understand
         should you begin to add comments.
 
-    - However, since that does not offer much in the way of prescriptive
-      guidance, here are some guidelines gathered from around the internet.
+      - However, since that does not offer much in the way of prescriptive
+        guidance, here are some guidelines gathered from around the internet.
           - A general rule of thumb, though not always true, is that comments
             should explain ***why*** something is being done in the code,
             rather than ***what*** the code is doing.[^butwhattabout]
@@ -49,6 +51,7 @@ parts of the code that cannot be made simpler--for instance, a clever arithmetic
 trick in a complicated interpolation scheme.
 [^dupe]: For example, this type of comment does not add any information and
 is unnecessary.
+
     ```c++
     // perform initialization
     this->initialize();

components/eamxx/docs/developer/style/style_guide_overview.md

@@ -5,21 +5,21 @@ For the purpose of this guide, we draw a distinction between these two related
 topics and loosely define them as:
 
 - **Style**
-    - Style is concerned with how the code ***reads*** on a lexical level as
-      well as with the structural and technical decisions that determine how
-      the code ***runs***.
-    - For example:
-        - Descriptive, as opposed to terse, variable names.
-        - Employing small, single-purpose functions.
-        - Usage or non-usage of advanced C++ features.
-        - The usage and content of comments.
+      - Style is concerned with how the code ***reads*** on a lexical level as
+        well as with the structural and technical decisions that determine how
+        the code ***runs***.
+      - For example:
+          - Descriptive, as opposed to terse, variable names.
+          - Employing small, single-purpose functions.
+          - Usage or non-usage of advanced C++ features.
+          - The usage and content of comments.
 - **Format**
-    - Format is the domain of how the code ***looks*** or how the code is
-      organized.
-    - The good news for formatting is that we enforce a strict, LLVM-based
-      formatting standard, and we employ
-      [`clang-format`](https://clang.llvm.org/docs/ClangFormat.html)
-      to automatically conduct and enforce this standard.
+      - Format is the domain of how the code ***looks*** or how the code is
+        organized.
+      - The good news for formatting is that we enforce a strict, LLVM-based
+        formatting standard, and we employ
+        [`clang-format`](https://clang.llvm.org/docs/ClangFormat.html)
+        to automatically conduct and enforce this standard.
 
 More detail regarding each of these topics is contained in the following
 sections.