serial: add JSDoc documentation for module functions and constants - #468
Merged
Merged
Conversation
The isCommentStart() helper requires a newline character before the /** sequence, which can never be satisfied for a module doc comment placed at the very top of a C source file. Such a comment is then treated as code and mangled into line comments by the source rewrite, silently dropping it from the generated documentation. Treat offset zero as a valid comment boundary, and skip the empty code chunk that results, whose line-comment rewrite would otherwise prepend a stray // sequence to the preserved doc comment. Signed-off-by: Jo-Philipp Wich <jo@mein.io>
Add the missing JSDoc documentation to the serial module, following the pattern established by the other lib modules: - module header describing the module and its import options - function documentation for all 21 exported functions, including parameter types and the null-on-error return contract - constant documentation for all 139 exported constants, grouped into apply modes, flush queues, termios flag sets, control character indices, baud rates, modem control line bits and the Linux-specific serial_struct flags and port types Signed-off-by: Jo-Philipp Wich <jo@mein.io>
jow-
force-pushed
the
feat/lib-serial-docs
branch
from
October 5, 2026 21:10
fa6b6d8 to
04d3ae5
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add the missing JSDoc documentation to the serial module, following
the pattern established by the other lib modules:
parameter types and the null-on-error return contract
into apply modes, flush queues, termios flag sets, control
character indices, baud rates, modem control line bits and the
Linux-specific serial_struct flags and port types
Also add the conventional copyright header, which turns out to be
required for the jsdoc c-transpiler to recognize the module doc
comment: the transpiler only preserves /** blocks preceded by a
newline, so a doc comment at the very top of the file is mangled
into line comments and silently dropped from the generated docs.
Signed-off-by: Jo-Philipp Wich jo@mein.io