Tracer documentation generation enhacements #5504
Conversation
* Add main part of consistency checker to trace-dispatcher * Enhance docu generation * Consistent renaming renaming for TraceControl members * Reflection messages documentation
* chaindb namespace fix * Move main part of consistency check to trace-dispatcher * Missing parts for doc generation
and fix typos
jutaro
force-pushed
the
jutaro/tracer-documentation
branch
from
e3b396e
to
bb93888
Compare
| import Cardano.Logging.ConfigurationParser | ||
| import Cardano.Logging.Types | ||
|
|
||
| -- | Warniings as a list of text |
|
|
||
| -- | Check if a single namespace is legal. Returns just a warning test, | ||
| -- if this is not the case | ||
| checkNamespace :: NSLookup -> [T.Text] -> Maybe T.Text |
There was a problem hiding this comment.
Please could you add a detailed comment of what 'legal' / consistent / well-formed actually means?
From the code I can infer that a namespace must have a valid lookup at each level of nesting to be considered legal. But what abstract condition is checked by that?
Maybe make a joint [Note] including comment from asNSLookup - it's not straightforward to see how the nested Map values are constructed from [[Text]]. But this is vital to understand how the check works. You could illustrate by including an example?
| numbers = fromString $ show (length dtBuilderList) <> " log messages." <> "\n\n" | ||
| legend = fromString $ "\9443 - This is the root of a tracer\n\n" | ||
| <> "\9442 - This is the root of a tracer that is silent because of the current configuration\n\n" | ||
| <> "\9436 - This is the root of a tracer, that provides metrics\n\n" |
There was a problem hiding this comment.
A general suggestion for these special characters: can we instead of inlining them, use a top-level definition (and use hex encoding for UTF codes), like so:
utf16CircledT :: Builder
utf16CircledT = singleton '\x24E3'
This would make any maintenance / change to the special chars much more easy. (EDIT: the type was just an example, it could as well be a Text)
This pull request addresses several enhancements related to Tracer documentation generation, ensuring consistency and improving the quality of the documentation. The key changes in this pull request include:
Addition of Main Part of Consistency Checker to Trace-Dispatcher: We've introduced the main part of the consistency checker to the trace-dispatcher, which ensures that traces remain consistent and accurate.
Enhancements to Documentation Generation: We've made improvements to the documentation generation process, resulting in more comprehensive and user-friendly documentation for the Tracer system.
Consistent Renaming for TraceControl Members: To maintain clarity and consistency within the codebase, we've applied consistent renaming to TraceControl members.
Documentation for Reflection Messages: We've added documentation for reflection messages, making it easier for developers to understand the purpose and usage of these messages.