From 92a184fbf8c2b5671032cfcad8ae2f1c9ee39ca7 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Thu, 20 Jun 2024 12:27:48 +0200 Subject: WIP more documentation --- makefile | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 makefile (limited to 'makefile') diff --git a/makefile b/makefile new file mode 100644 index 0000000..5f5340b --- /dev/null +++ b/makefile @@ -0,0 +1,5 @@ +all: doxygen + +doxygen: Doxyfile + doxygen + -- cgit v1.2.3 From 33d17dbab86c1277a1327273fb9753b2c98b7b03 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sat, 22 Jun 2024 14:32:19 +0200 Subject: more documentation --- Doxyfile | 6 ++++-- client/readme.md | 32 ++++++++++++++------------------ lib/i2ctcp/i2ctcpv1.h | 2 ++ lib/mpack/mpack.h | 31 ++++++++++++++++++++++++++----- main/readme.md | 3 +++ makefile | 9 ++++++++- puzzle/dummy/index.dox | 9 +++++++++ puzzle/neo/index.dox | 6 ++++++ puzzle/readme.md | 17 +++++++++++------ puzzle/vault/index.dox | 6 ++++++ readme.md | 22 ++++++++++++++++++++-- 11 files changed, 109 insertions(+), 34 deletions(-) create mode 100644 puzzle/dummy/index.dox create mode 100644 puzzle/neo/index.dox create mode 100644 puzzle/vault/index.dox (limited to 'makefile') diff --git a/Doxyfile b/Doxyfile index 2d600e7..af362dd 100644 --- a/Doxyfile +++ b/Doxyfile @@ -4,12 +4,12 @@ PROJECT_NAME = "puzzlebox" OUTPUT_DIRECTORY = doxygen INPUT += readme.md -INPUT += client INPUT += lib/mpack INPUT += lib/i2ctcp INPUT += lib/pbdrv +INPUT += client INPUT += main -INPUT += puzzle/dummy +INPUT += puzzle EXCLUDE = lib/mpack/src EXCLUDE_PATTERNS = **/build @@ -24,6 +24,8 @@ ALIASES += I2C="I²C" INPUT_FILTER = "sed -e 's/\\|\2<\/sup>C\>/\\I2C/g'" USE_MDFILE_AS_MAINPAGE = readme.md +HTML_INDEX_NUM_ENTRIES = 1 # collapse trees by default +REPEAT_BRIEF = NO INTERNAL_DOCS = YES EXTRACT_STATIC = YES diff --git a/client/readme.md b/client/readme.md index fcde40d..b9e0b09 100644 --- a/client/readme.md +++ b/client/readme.md @@ -1,3 +1,6 @@ +\defgroup pbc pbc +\brief Puzzle box client + # puzzle box client This folder contains the source code for the puzzle box client (pbc). This is a @@ -7,30 +10,21 @@ game operator to control and monitor the state of a puzzle box, but is also a useful debugging tool when developing puzzle modules, as it allows you to send arbitrary data over the puzzle bus. -## WIP TODO - -- cleanup - - separate ../shared/pb/moddrv.c into a puzzle module specific and 'common' bit - - use the common bit in i2c.cpp instead - - cast to structs in ../shared/pb/moddrv.c -- functionality - - print pretty tree of connected puzzle modules - - add enum to string functions in CLIENT ONLY - ## Features - List detected puzzle modules - Reset puzzle modules (individually or all to reset the box) - Skip puzzle modules (individually or all) - Request puzzle box state - -Debug only: -- Send arbitrary messages +- Debug: send arbitrary messages ## Building -PBC is a standard CMake project, but a [makefile](./makefile) is provided for -convenience (still requires CMake and Ninja are installed). +PBC is a standard CMake project. + +## Using + +See ./pbc.1 for usage. ## Send data @@ -45,8 +39,10 @@ send 0x39 68:65:6c:6c:6f 44 0x20 'world' 33 The data is concatenated, and may contain mixed types of literals -## known bugs (TODO) -- tab completion for `dump` seems to print garbage sometimes -- the send command with an address but no data causes a segmentation fault +## WIP TODO + +- add enum to string functions in CLIENT ONLY +- bug: tab completion for `dump` seems to print garbage sometimes +- bug: the send command with an address but no data causes a segmentation fault diff --git a/lib/i2ctcp/i2ctcpv1.h b/lib/i2ctcp/i2ctcpv1.h index d7bb29e..e9bc0d9 100644 --- a/lib/i2ctcp/i2ctcpv1.h +++ b/lib/i2ctcp/i2ctcpv1.h @@ -91,6 +91,8 @@ void i2ctcp_read_reset(i2ctcp_msg_t * target); */ bool i2ctcp_write(const i2ctcp_msg_t * target, char ** buf, size_t * buf_sz); +/// \} + #ifdef __cplusplus } #endif diff --git a/lib/mpack/mpack.h b/lib/mpack/mpack.h index 7c0c089..33521c4 100644 --- a/lib/mpack/mpack.h +++ b/lib/mpack/mpack.h @@ -2,18 +2,39 @@ #include "src/src/mpack/mpack.h" +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \defgroup mpack mpack + * \brief Mpack extensions specific to this project + * + * The mpack folder under `lib/` contains a CMakeLists.txt for integrating the + * mapck library with CMake, and includes an extension in the form of an + * additional utility function. + * + * \{ + */ + /** - * \brief read remaining bytes in reader without opening a tag first + * \brief Read remaining bytes in reader without opening a tag first * - * \param reader pointer to mpack reader object - * \param p pointer to write data to - * \param count maximum number of bytes to read + * \param reader Pointer to mpack reader object + * \param p Pointer to write data to + * \param count Maximum number of bytes to read * * This function reads *up to* the amount of bytes specified in \p count, or * less if there is less remaining data in the buffer. If \p count is equal to * 0, all remaining data in the buffer is read. * - * \return amount of bytes read + * \return Amount of bytes read */ size_t mpack_read_remaining_bytes(mpack_reader_t * reader, char * p, size_t count); +/// \} + +#ifdef __cplusplus +} +#endif + diff --git a/main/readme.md b/main/readme.md index 28fcfad..85a3fca 100644 --- a/main/readme.md +++ b/main/readme.md @@ -1,3 +1,6 @@ +\defgroup main main +\brief Main controller software + # main controller firmware This directory contains the software for the main controller of the Puzzle Box. diff --git a/makefile b/makefile index 5f5340b..090877e 100644 --- a/makefile +++ b/makefile @@ -1,5 +1,12 @@ all: doxygen -doxygen: Doxyfile +.PHONY: FORCE + +doxygen: Doxyfile FORCE doxygen +FMT += $(shell git ls-files '*.h' '*.c' '*.cpp') +format: FORCE + clang-format -i $(FMT) + clang-tidy --fix-errors $(FMT) + diff --git a/puzzle/dummy/index.dox b/puzzle/dummy/index.dox new file mode 100644 index 0000000..918bf7f --- /dev/null +++ b/puzzle/dummy/index.dox @@ -0,0 +1,9 @@ +// vim:ft=doxygen +/** +\ingroup puz +\defgroup puz_dummy Dummy +\brief Demo puzzle module + +The dummy puzzle module consists of an empty Arduino sketch, and can be used as +a starting point for developing new puzzle modules. +*/ diff --git a/puzzle/neo/index.dox b/puzzle/neo/index.dox new file mode 100644 index 0000000..14cefdc --- /dev/null +++ b/puzzle/neo/index.dox @@ -0,0 +1,6 @@ +// vim:ft=doxygen +/** +\ingroup puz +\defgroup puz_neo Neo +\brief NeoTrellis puzzle module +*/ diff --git a/puzzle/readme.md b/puzzle/readme.md index 59c10b1..959c506 100644 --- a/puzzle/readme.md +++ b/puzzle/readme.md @@ -1,15 +1,20 @@ +\defgroup puz puzzle +\brief Puzzle modules + # puzzles This folder contains the source code for all puzzle modules. ## Arduino-based puzzle modules -Because of the poorly designed hardware (21-22) used during development -(23-24), some puzzle modules ended up being developed using Arduino boards. All -libraries in this repository use CMake for building (for consistency), which -also means the Arduino based puzzle modules use CMake. The CMakeLists.txt of -some puzzles uses the [Arduino-CMake-Toolchain][arduino-cmake]. To build any of -these subfolders, make sure you have done the following: +> [!NOTE] +> Because of the poorly designed hardware (21-22) used during development +> (23-24), all puzzle modules ended up being developed using Arduino boards. + +All libraries in this repository use CMake for building (for consistency), +which also means the Arduino based puzzle modules use CMake. The CMakeLists.txt +of some puzzles uses the [Arduino-CMake-Toolchain][arduino-cmake]. To build any +of these subfolders, make sure you have done the following: - Install the official Arduino IDE - Open "Tools" > "Board" > "Board manager" diff --git a/puzzle/vault/index.dox b/puzzle/vault/index.dox new file mode 100644 index 0000000..b14e616 --- /dev/null +++ b/puzzle/vault/index.dox @@ -0,0 +1,6 @@ +// vim:ft=doxygen +/** +\ingroup puz +\defgroup puz_vault Vault +\brief Vault puzzle module +*/ diff --git a/readme.md b/readme.md index 457ffaa..a6365c0 100644 --- a/readme.md +++ b/readme.md @@ -11,6 +11,20 @@ project. The software in this repository should be easily portable to various other microcontrollers, and a recommendation is made in the [design document](docs/design.adoc). +## Documentation + +This project is documented using Doxygen. To generate HTML docs, run + +``` +$ make doxygen +``` + +and open in a browser. + +If you are viewing this page from Doxygen, please take a look at +[topics](/topics.html) for a comprehensive list of components within this +project. + ## Tidyness Please keep this repository tidy by being aware of the following conventions! @@ -36,8 +50,12 @@ An `.editorconfig` file is provided in this repository. Please install the [EditorConfig](https://editorconfig.org/) plugin for your text editor of choice to automatically use these. -Currently, no linter/formatter is configured for maintaining consistent code -style. +There are also `.clang-tidy` and `.clang-format` files, which can be enforced +by running + +``` +$ make format +``` ## Submodules -- cgit v1.2.3 From 9a24fe708770d717ecb8cbe45fe24922d21b5838 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sat, 22 Jun 2024 17:40:40 +0200 Subject: tweak clang format settings --- .clang-format | 10 ++++++++-- makefile | 3 ++- 2 files changed, 10 insertions(+), 3 deletions(-) (limited to 'makefile') diff --git a/.clang-format b/.clang-format index f180135..064fa96 100644 --- a/.clang-format +++ b/.clang-format @@ -1,11 +1,10 @@ --- AccessModifierOffset: -4 -AlignConsecutiveAssignments: true AllowShortIfStatementsOnASingleLine: AllIfsAndElse AllowShortLoopsOnASingleLine: true BasedOnStyle: LLVM BreakBeforeBraces: Attach -ColumnLimit: 180 +ColumnLimit: 80 EmptyLineBeforeAccessModifier: Always IndentAccessModifiers: false IndentCaseLabels: true @@ -14,6 +13,13 @@ Language: Cpp Standard: Cpp11 TabWidth: 4 UseTab: Always +PointerAlignment: Middle +SpaceAfterCStyleCast: true +AlignConsecutiveAssignments: + Enabled: false +AlignTrailingComments: + Kind: Leave +ReflowComments: false ... # vim: ft=yaml diff --git a/makefile b/makefile index 090877e..2ea1c3d 100644 --- a/makefile +++ b/makefile @@ -8,5 +8,6 @@ doxygen: Doxyfile FORCE FMT += $(shell git ls-files '*.h' '*.c' '*.cpp') format: FORCE clang-format -i $(FMT) - clang-tidy --fix-errors $(FMT) +# clang tidy doesn't work that well :/ +# clang-tidy --fix-errors $(FMT) -- cgit v1.2.3