1- [ ![ Coverage Status] ( https://coveralls.io/repos/github/blues/note-c/ badge.svg?branch=master )] ( https://coveralls.io/github/blues/note-c?branch=master )
1+ [ ![ Coverage Status] [ coverage badge]] [ coverage details ]
22
33# note-c
44
@@ -12,22 +12,116 @@ Notes to [Notehub.io][notehub].
1212This library is used by the [ note-arduino library] [ note-arduino ] , which includes
1313it as a git subtree.
1414
15- ## Documentation
15+ ## API Documentation
1616
17- The documentation for this library can be found [ here] ( https://blues.github.io/ note-c/index.html ) .
17+ The API documentation for this library can be found [ here] [ note-c API docs ] .
1818
19- ## CMake
19+ ## Logging Control
2020
21- The CMake build system is primarily here for testing note-c on a development
22- machine. You can use it to generate a static or shared note-c library, but
23- embedded users will typically just compile all the .c source files into their
24- firmware image. For more on testing, see test/README.md.
21+ ` note-c ` provides a comprehensive and flexible logging functionality.
2522
26- ### Options
23+ To activate logging, you must provide a callback for logging via
24+ ` hookDebugOutput() ` . The callback takes the following form:
2725
28- - BUILD_TESTS: Build the tests. See the tests directory. Default: ON.
29- - BUILD_SHARED_LIBS: Build the note-c library as shared instead of static. This
30- reduces the total size of the compiled tests. Default: ON.
26+ ``` c
27+ typedef size_t (* debugOutputFn) (const char * text);
28+ ```
29+
30+ The callback is responsible for taking a character array (C-style string) and
31+ returning the number of bytes processed (written out) as confirmation. The
32+ exact implementation will be up to the user who provided the function pointer,
33+ but its presence will active logging in the library.
34+
35+ ### Library Logging
36+
37+ #### Log Levels
38+
39+ `note-c` provides for four (4) levels of logging. Here they are listed from
40+ most severe to most verbose:
41+
42+ 0. `NOTE_C_LOG_LEVEL_ERROR`
43+ 1. `NOTE_C_LOG_LEVEL_WARN`
44+ 2. `NOTE_C_LOG_LEVEL_INFO`
45+ 3. `NOTE_C_LOG_LEVEL_DEBUG`
46+
47+ By default, `note-c` logs at `NOTE_C_LOG_LEVEL_INFO`.
48+
49+ #### Default Logging Behavior
50+
51+ To modify the default behavior, you may specify the desired log level at compile
52+ time, as follows:
53+
54+ ```sh
55+ -DNOTE_C_LOG_LEVEL=0
56+ ```
57+
58+ _ ** NOTE:** In the example above, you will notice we used zero (` 0 ` ), instead of
59+ ` NOTE_C_LOG_LEVEL_ERROR ` . This is because the warning constants are internal to
60+ the library, and not available in the context of the command line._
61+
62+ Here, we have decided to show only the most severe (i.e. ` [ERROR] ` ) logs.
63+ Alternatively, you may set the level to any of the values listed above.
64+
65+ #### Dynamic Logging Behavior
66+
67+ In the previous section, we discussed setting the base (or default) logging
68+ behavior for the library. However, you may also set the log level dynamically,
69+ during runtime, by using the ` NoteSetLogLevel() ` API.
70+
71+ ``` c
72+ NoteSetLogLevel (NOTE_C_LOG_LEVEL_WARN);
73+ ```
74+
75+ ### Notecard Sync Logging (`[SYNC]`)
76+
77+ Tangential to the standard logging behavior, `note-c` also provides a helper
78+ function to invoke/extract synchronization logs from the Notecard.
79+
80+ - `NoteDebugSyncStatus()`
81+
82+ Instead of toggling features inside the library, this helper functions sends a
83+ request to the Notecard to inquire about its synchronization status and logs
84+ those details.
85+
86+ The function is designed to be called in a loop and throttled by a parameter.
87+ See [the documentation page][NoteDebugSyncStatus] for more information.
88+
89+ ## Versioning
90+
91+ The `note-c` versioning scheme is a variant of [Semantic
92+ Versioning](https://semver.org/).
93+
94+ Below is a high-level overview of the major/minor/patch versions:
95+
96+ - Major Version: Signals incompatible API changes.
97+ - Minor Version: Signals added functionality in a backward compatible manner.
98+ - Patch Version: Signals backward compatible bug fixes.
99+
100+ Beyond the SemVer foundation, Blues has imposed additional requirements for a
101+ version to be considered valid:
102+
103+ - Major/minor/patch versions SHALL NOT be zero.
104+ - For anything other than major version, version numbers MUST NOT contain
105+ EITHER leading zeroes OR trailing zeroes (e.g. version `1.10.2` is invalid).
106+
107+ > Example version progression:
108+ >
109+ > `1.8.1`, `1.9.1`, `1.9.2`, `1.11.1`, `1.11.2`, `1.11.3`, `1.12.1`, `2.1.1`
110+
111+ These additional constraints have been observed to help disambiguate versions
112+ and reduce support burden.
113+
114+ ### Version Artifacts
115+
116+ The version can be referenced/tested programmatically via the following
117+ preprocessor defined integers found in `note.h`:
118+
119+ - `NOTE_C_VERSION_MAJOR`
120+ - `NOTE_C_VERSION_MINOR`
121+ - `NOTE_C_VERSION_PATCH`
122+
123+ The version may also be logged via the preprocessor defined string literal,
124+ `NOTE_C_VERSION`.
31125
32126## Contributing
33127
@@ -57,8 +151,12 @@ Copyright (c) 2019 Blues Inc. Released under the MIT license. See
57151[LICENSE](LICENSE) for details.
58152
59153[blues]: https://blues.com
154+ [code of conduct]: https://blues.github.io/opensource/code-of-conduct
155+ [coverage badge]: https://coveralls.io/repos/github/blues/note-c/badge.svg?branch=master
156+ [coverage details]: https://coveralls.io/github/blues/note-c?branch=master
157+ [NoteDebugSyncStatus]: https://blues.github.io/note-c/api_reference.html#c.NoteDebugSyncStatus
60158[notehub]: https://notehub.io
61159[note-arduino]: https://github.com/blues/note-arduino
160+ [note-c API docs]: https://blues.github.io/note-c/index.html
62161[note-go]: https://github.com/blues/note-go
63162[note-python]: https://github.com/blues/note-python
64- [ code of conduct ] : https://blues.github.io/opensource/code-of-conduct
0 commit comments