Move developer documentation to repo

patrick96 2022-04-03 14:25:25 +02:00
parent 3ef431f0b3
commit a3b5879b70
No known key found for this signature in database
GPG Key ID: 521E5E03AEBCA1A7
4 changed files with 14 additions and 86 deletions

8
Distro-Specific-Setup.md Normal file

@ -0,0 +1,8 @@
This page contains tips for setting up your polybar environment in different
distros, contributed by the community.
Also check out the [developer
documentation](https://polybar.readthedocs.io/en/latest/dev/getting-started.html).
If you run into any quirks in your distro, feel free to document them here.
## Nix

@ -1,63 +1 @@
❗️**Note:** This document is a work in progress and is extended as we go.
There is a `.editorconfig` file in the project root that defines some basic guidelines, mainly relating to indentation.
We loosely follow the [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) with exceptions and important rules noted here.
## Code Formatting
We use `clang-format` for code formatting, the style rules are defined in
`.clang-format`, before submitting a PR, make sure to run the following command
on all the C++ files you changed:
```bash
clang-format -style=file -i <FILES>
```
**Note:** Depending on which file you change, this may produce a lot of changes
because we have not run `clang-format` on all files in the project. This is
fine.
### Line Width
Lines should not be longer than 120 characters, `clang-format` will enforce this
when run. However, try to keep lines under 80 characters if it seems reasonable
in the current situation.
In some cases it makes sense to have lines longer than 80 characters for
readability. But long lines can just the same be unreadable, for example if you
have long if-conditions or use complex expressions as function parameters. Make
sure you only use longer lines if keeping it under 80 would be less readable.
## Comments
Use Doxygen `/** */` comments in front of functions, methods, types, members and
classes:
```cpp
/**
* @brief Generates a config object from a config file
*
* For modularity the parsing and storing of the config is separated
*/
class config_parser {
...
/**
* @brief Is used to resolve ${root...} references
*/
string m_barname;
...
}
```
For all other comments use `//` for single-line and `/* */` for multi-line comments.
Your comments should describe the intent and purpose of your code, not necessarily what it does.
## Header Files
Header files generally end in `.hpp`.
We don't use include guards, but start the header file with the following line:
```cpp
#pragma once
```
**❗This page has moved. Please find the newest version of this document [here](https://polybar.readthedocs.io/en/latest/dev/style-guide.html).❗️❗️❗️**

@ -1,20 +1 @@
Polybar uses [googletest](https://github.com/google/googletest/blob/main/docs/primer.md)
as its testing framework. Tests live in the `tests/` directory. They can be
enabled during cmake with `-DBUILD_TESTS=ON` and compiled with `make
all_unit_tests`.
Each test gets its own executable in `build/tests`, which can be executed to run
a specific test.
Running all tests is preferably done with the following command:
```bash
make check
```
This runs all available tests and prints the output in color for failed tests
only.
## Adding New Tests
All new tests need to be added to the `tests/CMakeLists.txt` file. Have a look
at the other unit tests in `tests/unit_tests` to see how to write tests for your
code.
**❗This page has moved. Please find the newest version of this document [here](https://polybar.readthedocs.io/en/latest/dev/testing.html).❗️❗️❗️**

@ -9,10 +9,11 @@
- 💬 [Inter process messaging](https://polybar.readthedocs.io/en/stable/user/ipc.html)
- 🤫 [Known Issues](./Known-Issues)
- 📦 [Packaging Polybar](https://polybar.readthedocs.io/en/latest/dev/packaging.html)
- For Developers:
- [For Developers](https://polybar.readthedocs.io/en/latest/dev/getting-started.html):
* 📚 [Release Guidelines](https://polybar.readthedocs.io/en/latest/dev/release-workflow.html)
* 🎨 [Style Guide](./Style-Guide)
* 🧪 [Testing](./Testing)
* 🎨 [Style Guide](https://polybar.readthedocs.io/en/latest/dev/style-guide.html)
* 🧪 [Testing](https://polybar.readthedocs.io/en/latest/dev/testing.html)
* 🐧 [Distro Specific Setup](./Distro-Specific-Setup)
- Modules:
* [alsa](./Module:-alsa)
* [backlight](./Module:-backlight)