🎨 Cleanup COC, README and style

CODE_OF_CONDUCT.md

@@ -14,22 +14,22 @@ race, religion, or sexual identity and orientation.
 Examples of behavior that contributes to creating a positive environment
 include:
 
-*   Using welcoming and inclusive language
-*   Being respectful of differing viewpoints and experiences
-*   Gracefully accepting constructive criticism
-*   Focusing on what is best for the community
-*   Showing empathy towards other community members
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
 
 Examples of unacceptable behavior by participants include:
 
-*   The use of sexualized language or imagery and unwelcome sexual attention or
-    advances
-*   Trolling, insulting/derogatory comments, and personal or political attacks
-*   Public or private harassment
-*   Publishing others' private information, such as a physical or electronic
-    address, without explicit permission
-*   Other conduct which could reasonably be considered inappropriate in a
-    professional setting
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
 
 ## Our Responsibilities
 
@@ -69,13 +69,12 @@ dispute. If you are unable to resolve the matter for any reason, or if the
 behavior is threatening or harassing, report it. We are dedicated to providing
 an environment where participants feel welcome and safe.
 
-Reports should be directed to *[PROJECT STEWARD NAME(s) AND EMAIL(s)]*, the
-Project Steward(s) for *[PROJECT NAME]*. It is the Project Steward’s duty to
-receive and address reported violations of the code of conduct. They will then
-work with a committee consisting of representatives from the Open Source
-Programs Office and the Google Open Source Strategy team. If for any reason you
-are uncomfortable reaching out to the Project Steward, please email
-[email protected].
+Reports should be directed to the libhal email. It is the Project Steward’s
+duty to receive and address reported violations of the code of conduct. They
+will then work with a committee consisting of representatives from the Open
+Source Programs Office and the Google Open Source Strategy team. If for any
+reason you are uncomfortable reaching out to the Project Steward, please email
+[email protected].
 
 We will investigate every complaint, but you may not receive a direct response.
 We will use our discretion in determining when and how to follow up on reported

README.md

@@ -4,11 +4,20 @@ Organization wide repo for docs, assets, and tools any other static information.
 
 ## Updating the docs
 
-libhal uses [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) for our static documentation and [sphinx](https://www.sphinx-doc.org/en/master/) for our API documentation
+libhal uses [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) for
+our static documentation and [sphinx](https://www.sphinx-doc.org/en/master/)
+for our API documentation
 
-If you'd like to contribute to the libhal website and documentation you can do so by quickly setting up the enviornement by running the following commands. Please note that the build script is designed for a bash environment and is intended to be used on unix-based operating systems. The documentation is fully compatible with Windows, however you will need to write your own `.bat` install script or run the commands individually (as well as switch from bash's commands to powershell or command prompt's variants of them). 
+If you'd like to contribute to the libhal website and documentation you can do
+so by quickly setting up the enviornement by running the following commands.
+Please note that the build script is designed for a bash environment and is
+intended to be used on unix-based operating systems. The documentation is fully
+compatible with Windows, however you will need to write your own `.bat` install
+script or run the commands individually (as well as switch from bash's commands
+to powershell or command prompt's variants of them).
 
-Please first install python 3.10 or later. Then run the following to install the required packages for running the documentation.
+Please first install python 3.10 or later. Then run the following to install
+the required packages for running the documentation.
 
 ```bash
 pip install -r requirements.txt
@@ -23,33 +32,40 @@ Now to actually build the documentation.
 > [!NOTE]
 > You may need to run `chmod +x build.sh` to run it.
 
-
 Finally to serve the documentation:
+
 ```bash
-    mkdocs serve
+mkdocs serve
 ```
+
 The page should be available on this address `http://127.0.0.1:8000`.
 
 Now whenever you update the markdown in the mkdocs directory, the page will
 auto-reload with your changes, *however* if you are making changes to the API documentation, you must rebuild the documentation.
 If you changed just `rst` or `md` files in the `sphinx` directory you can simply run the command inside the `sphinx` directory.
 
 ```bash
-    sphinx-build -b html -Dbreathe_projects.libhal=../doxygen_output/xml . output
+sphinx-build -b html -Dbreathe_projects.libhal=../doxygen_output/xml . output
 ```
+
 If things changed in the actual code for the documentation, you will need to build the doxygen files as well.
 Run the following starting in the root of this repo.
 
 ```bash
-    doxygen Doxyfile.in
-    cd sphinx
-    sphinx-build -b html -Dbreathe_projects.libhal=../doxygen_output/xml . output
+doxygen Doxyfile.in
+cd sphinx
+sphinx-build -b html -Dbreathe_projects.libhal=../doxygen_output/xml . output
 ```
 
-Checkout [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) for more details
-on the features that can be used for the static side of this site.
+Checkout [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) for
+more details on the features that can be used for the static side of this site.
 
-Checkout [sphinx](https://www.sphinx-doc.org/en/master/) for how to use sphinx at a basic level, [breathe](https://breathe.readthedocs.io/en/latest/) on how to use doxygen directives on how to organize your code inside of sphinx `rst` or `md` files, and finally the [theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/) for theme specific uses for the API documentation.
+Checkout [sphinx](https://www.sphinx-doc.org/en/master/) for how to use sphinx
+at a basic level, [breathe](https://breathe.readthedocs.io/en/latest/) on how
+to use doxygen directives on how to organize your code inside of sphinx `rst`
+or `md` files, and finally the
+[theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/) for theme
+specific uses for the API documentation.
 
 ## Contributing
 
@@ -58,10 +74,3 @@ See [`CONTRIBUTING.md`](CONTRIBUTING.md) for details.
 ## License
 
 Apache 2.0; see [`LICENSE`](LICENSE) for details.
-
-## Disclaimer
-
-This project is not an official Google project. It is not supported by
-Google and Google specifically disclaims all warranties as to its quality,
-merchantability, or fitness for a particular purpose.
-

mkdocs/contributor_guide/style.md

@@ -40,7 +40,7 @@ Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines).
 
 ## S.2 Refrain from performing manual bit manipulation
 
-Use `hal::bit` from `libhal-util` library to perform bitwise operations
+Use `hal::bit_modify` from `libhal-util` library to perform bitwise operations
 operations.
 
 ## S.3 Refrain from using MACROS
@@ -55,22 +55,23 @@ in writing out the boilerplate.
 Only use preprocessor `#if` and the like if it is impossible to use
 `if constexpr` to achieve the same behavior.
 
-## S.4 Never include C++ stream libraries
+## S.4 Never include C++ `<iostream>` libraries
 
 Applications incur an automatic 150kB space penalty for including any of the
 ostream headers that also statically generate the global `std::cout` and the
 like objects. This happens even if the application never uses any part of
-`<iostream>` library.
+`<iostream>` library. `<iostream>` can be used in libraries that will only be
+used for host side testing.
 
 ## S.5 Refrain from memory allocations
 
 Interfaces and drivers should refrain from APIs that force memory allocations
 or implementations that allocate memory from heap. This means avoiding STL
 libraries that allocate such as `std::string` or `std::vector`.
 
-Many embedded system applications, especially the real time ones, do not allow
-dynamic memory allocations. There are many reasons for this that can be found
-MISRA C++ and AutoSAR.
+Many embedded system applications, especially the real time applications, do
+not allow dynamic memory allocations. There are many reasons for this that can
+be found MISRA C++ and AutoSAR.
 
 ## S.6 Drivers should not log to STDOUT or STDIN
 
@@ -100,10 +101,10 @@ without giving control back to the application are prohibited.
 
 As an example drivers should never call:
 
-  - `std::abort()`
-  - `std::exit()`
-  - `std::terminate()`
-  - any of their variants
+- `std::abort()`
+- `std::exit()`
+- `std::terminate()`
+- any of their variants
 
 This includes placing an **infinite loop block** in a driver.
 
@@ -152,7 +153,7 @@ class target {
 See [private virtual method](http://www.gotw.ca/publications/mill18.htm)
 for more details. Rationale can be found within that link as well.
 
-## S.10 Avoid using `bool` as ...
+## S.10 Avoid using `bool` as:
 
 ### S.10.1 an object member