Eliminating doxygen warnings by fixing the documentation #889
Conversation
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
akosthekiss
added
enhancement
|
LGTM, please squash before merge |
akosthekiss
force-pushed
the
doc-fixes
branch
from
96dc9d9 to
47a6650
Compare
* Fix "end of file while inside a group" doxygen warnings. * Fix "unknown command" doxygen warnings caused by incorrect argument references. Instead of `@foo`, `@a foo` is the proper format. * Fix "unknown command" doxygen warnings caused by incorrect parameter direction specifications. Instead of `@in`, `@out`, and `@in-out`, `[in]`, `[out]`, and `[in,out]` are the proper formats. * Wrapping special characters in quotes to avoid doxygen confusion. Raw pipe, semicolon, dot, backslash, etc. characters can drive doxygen into various misinterpretations and warnings. E.g.: ``` End of list marker found without any preceding list items Found unknown command ``` Putting quotes around such text snipets eliminates the errors. * Fix the documentation of `ecma_builtin_global_object_print`. Raw <> and \ sequences confused doxygen in various ways (it tried to interpret them as XML tags and doxygen commands). * Fix "ignoring title that does not match old title" doxygen warnings. At some places, the group titles were out of sync, at others, the group names were incorrect. * Fix "parameters are not documented" doxygen warnings. Fixing various typos in the inline parameter documentations (`/*`, `/**`, `/** <`, and `/**>` are all considered incorrect, the right format is `/**<`). JerryScript-DCO-1.0-Signed-off-by: Akos Kiss [email protected]
akosthekiss
force-pushed
the
doc-fixes
branch
from
47a6650 to
0d7ea70
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
I've worked my way through the warnings emitted by doxygen, fixing one group of related issues at a time. The documentation is still far from being perfect -- or, from being consistent -- but now the comments are syntactically correct from doxygen's point of view, at least.