Reduce Doxygen warnings #3170
Reduce Doxygen warnings #3170
Conversation
johnnonweiler
requested review from
cesaro,
cristina-david,
kroening,
NathanJPhillips,
peterschrammel,
pkesseli,
smowton,
tautschnig and
thk123
as code owners
| @@ -19,7 +19,7 @@ class goto_model_functiont; | |||
| /// Replace calls to nondet library functions with an internal nondet | |||
| /// representation. | |||
| /// \param goto_model: The goto program to modify. | |||
| void replace_java_nondet(goto_modelt &); | |||
| void replace_java_nondet(goto_modelt &goto_model); | |||
There was a problem hiding this comment.
⛏️ Probably the fix is to move the documentation into the cpp file as per coding guidelines.
jbmc/src/java_bytecode/java_types.h
Outdated
| @@ -695,7 +695,7 @@ inline typet java_type_from_string_with_exception( | |||
| } | |||
|
|
|||
| /// Get the index in the subtypes array for a given component. | |||
| /// \param t The type we search for the subtypes in. | |||
| /// \param gen_types The subtypes array. | |||
There was a problem hiding this comment.
Nit-pick: add a colon after gen_types as is recommended in the coding guidelines (but arguably it's not done here for the other parameters).
| @@ -261,6 +261,8 @@ bool read_object_and_link( | |||
|
|
|||
| /// \brief reads an object file, and also updates the config | |||
| /// \param file_name file name of the goto binary | |||
| /// \param dest_symbol_table symbol table to update | |||
| /// \param dest_functions collection of goto functions to update | |||
There was a problem hiding this comment.
Nit-pick as above: add colons
src/util/std_types.h
Outdated
| @@ -79,7 +79,7 @@ class symbol_typet:public typet | |||
|
|
|||
| /// Check whether a reference to a typet is a \ref symbol_typet. | |||
| /// \param type Source type. | |||
| /// \return True if \param type is a \ref symbol_typet. | |||
| /// \return True if type is a \ref symbol_typet. | |||
There was a problem hiding this comment.
Ok for correct syntax, but is there some way to make Doxygen understand that this "type" refers to the named parameter "type"? I believe this is what the author intended.
There was a problem hiding this comment.
I couldn't find a way to explicitly link it to the parameter. I tried adding emphasis, or marking it as code, but I think it looks best as plain text.
There was a problem hiding this comment.
I hadn't seen that, thanks. It certainly looks from the Doxygen documentation like that is the way to go (https://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdp). Their example looks good:
However, it doesn't look so good in the documentation generated for cbmc:
I guess it's probably best to use the \p in the cbmc documentation now, and then possibly (in future) consider changing the cbmc documentation formatting so that it is more like the standard Doxygen formatting.
| @@ -19,7 +19,7 @@ class goto_model_functiont; | |||
| /// Replace calls to nondet library functions with an internal nondet | |||
| /// representation. | |||
| /// \param goto_model: The goto program to modify. | |||
| void replace_java_nondet(goto_modelt &); | |||
| void replace_java_nondet(goto_modelt &goto_model); | |||
There was a problem hiding this comment.
Passed Diffblue compatibility checks (cbmc commit: 21c7bc9).
Build URL: https://travis-ci.com/diffblue/test-gen/builds/87929992
Doxygen produces warnings if some parameters are documentated and not others, or if there is documentation for parameters which don't exist.
|
@tautschnig I have moved the documentation to the cpp file, and added some colons. |
There was a problem hiding this comment.
This PR failed Diffblue compatibility checks (cbmc commit: cfe83b9).
Build URL: https://travis-ci.com/diffblue/test-gen/builds/87952598
Status will be re-evaluated on next push.
Please contact @peterschrammel, @thk123, or @allredj for support.
Common spurious failures:
- the cbmc commit has disappeared in the mean time (e.g. in a force-push)
- the author is not in the list of contributors (e.g. first-time contributors).
The incompatibility may have been introduced by an earlier PR. In that case merging this
PR should be avoided unless it fixes the current incompatibility.
There was a problem hiding this comment.
Passed Diffblue compatibility checks (cbmc commit: 20a8fe5).
Build URL: https://travis-ci.com/diffblue/test-gen/builds/87954380
Before this commit, get_xml_options had the parameters "(const class xmlt &xml, cmdlinet &cmdline)" in the header file, and "(const xmlt &xml, cmdlinet &cmdline)" in the cpp file. Doxygen then produced a warning "no matching class member found". This commit adds a forward declaration "class xmlt;" in the header file, so that both versions of get_xml_options can have identical parameter lists.
Replace 'signed int' with 'int', and 'unsigned int' with 'unsigned', so that .cpp and .h files are consistent, and doxygen doesn't get confused
A doxygen \param comment in the header file was referring to the 'goto_model' parameter which was named only in the cpp file, and doxygen complained that it could not find the parameter. (Moved other comments for consistency.)
Doxygen was warning that the argument 'type' has muliple @param documentation sections, and producing incorrect documentation.
There was a problem hiding this comment.
Passed Diffblue compatibility checks (cbmc commit: 48061b4).
Build URL: https://travis-ci.com/diffblue/test-gen/builds/87966511
Following on from #3115, this addresses some more of the warnings that are produced when running doxygen. (Note: Unlike the previous PR, these changes are not limited to changes to the documentation. For example, changing int type specifiers to equivalent types to help Doxygen matching things up.)
This PR addresses some of the issues in java_bytecode, goto-programs, util and cbmc.
Please see the individual commits for details.