Update docs in annotate code API #17397
Conversation
There was a problem hiding this comment.
Comment for RCodeAnnotationType isn't up to date anymore. The first sentence provides zero information.
There are now more than two types. It would probably be more suitable to document each enum value inline. Here is an exmple for that https://www.doxygen.nl/manual/docblocks.html#memberdoc
Done. |
Done. |
There was a problem hiding this comment.
As a general advice if all the words in comment are the same as declaration it means that documentation doesn't provide reader with any information and it was waste of time for both person writing it and person reading it.
Don't write "documentation" for the sake of writing it, write it to provide useful information to the caller of function about how to use it correctly and what can it be used for. Avoid repeating things which are already expressed in the naming of function and the type system.
Some bad examples:
RCodeAnnotationType type; /**< Type of the annotation. */- who could have guessed that code annnotation type named type is type of the annotation.R_CODE_ANNOTATION_TYPE_FUNCTION_PARAMETER, /*!< Specified range in annotation represents a function parameter. */
@karliss I'm not sure what all are unnecessary explanations. The second one here doesn't seem useless to me. If it is useless, I don't see how any documentation for the |
Yes most of the descriptions for r_code_annotation_type_t don't provide any information. I think one or two had unique words providing little bit of additional information. |
…edCode (#17429) * Annotation for function name (#17204) * Annotations for Constant Variables and Global Variables for the decompiler (#17281) * Annotation For Function Variables (#17375) * function variable annotation added (includes local variable and function parameter) * API for checking if an annotation is a reference or function variable. (#17386) * Update docs in annotate code API (#17397) * Unit tests for annotated code API (#17403)
…edCode (radareorg#17429) * Annotation for function name (radareorg#17204) * Annotations for Constant Variables and Global Variables for the decompiler (radareorg#17281) * Annotation For Function Variables (radareorg#17375) * function variable annotation added (includes local variable and function parameter) * API for checking if an annotation is a reference or function variable. (radareorg#17386) * Update docs in annotate code API (radareorg#17397) * Unit tests for annotated code API (radareorg#17403)
…edCode (#17429) * Annotation for function name (#17204) * Annotations for Constant Variables and Global Variables for the decompiler (#17281) * Annotation For Function Variables (#17375) * function variable annotation added (includes local variable and function parameter) * API for checking if an annotation is a reference or function variable. (#17386) * Update docs in annotate code API (#17397) * Unit tests for annotated code API (#17403)
Your checklist for this pull request
Detailed description
Earlier, I had used kernel-docs documentation style for documenting new API functions created for the annotations in the decompiler. This PR replaces these documentations by Doxygen.
...
Test plan
...
Closing issues
...