API for checking if an annotation is a reference or function variable. by NirmalManoj · Pull Request #17386 · radareorg/radare2

NirmalManoj · 2020-07-31T14:04:02Z

Your checklist for this pull request

I've read the guidelines for contributing to this repository
I made sure to follow the project's coding style
I've added tests that prove my fix is effective or that my feature works (if possible)
I've updated the documentation and the radare2 book with the relevant information (if needed)

Detailed description

This PR implements the following two functions. Read the documentation below.

/**
 * is_annotation_reference() - Checks if the specified annotation is a reference.
 * @annotation: Pointer to an annotation.
 * 
 * This function recognizes the type of the specified annotation and returns true if its
 * type is any of the following three: R_CODE_ANNOTATION_TYPE_GLOBAL_VARIABLE,
 * R_CODE_ANNOTATION_TYPE_CONSTANT_VARIABLE, R_CODE_ANNOTATION_TYPE_FUNCTION_NAME
 * 
 * Return: Returns true if the specified annotation is a reference.
 */
R_API bool is_annotation_reference(RCodeAnnotation *annotation);
/**
 * is_annotation_variable() - Checks if the specified annotation is a function variable.
 * @annotation: Pointer to an annotation.
 * 
 * This function recognizes the type of the specified annotation and returns true if its
 * type is any of the following two: R_CODE_ANNOTATION_TYPE_LOCAL_VARIABLE,
 * R_CODE_ANNOTATION_TYPE_FUNCTION_PARAMETER
 * 
 * Return: Returns true if the specified annotation is a function variable.
 */
R_API bool is_annotation_variable(RCodeAnnotation *annotation);

...

Test plan

Check code.
Fetch and compile Cutter PR #2352 after compiling this PR. That PR uses this API. So you can check if it's working correctly or not.

...

Closing issues

...

karliss · 2020-07-31T14:15:21Z

 * Return: Nothing.
 */
 R_API void r_annotation_free(void *e, void *user);
+/**


Please don't invent your own documentation comment style. If you use doxygen style comments do so consistently. They are not only for human reading but also consumption by tools. See the documentation https://www.doxygen.nl/manual/index.html

Radare2 uses this style https://www.kernel.org/doc/html/v4.16/doc-guide/kernel-doc.html#how-to-format-kernel-doc-comments
I have been told to use this and all functions in r_annotated_code.h are documented using this style.

See here: https://github.com/radareorg/radare2/blob/master/libr/include/r_util/r_annotated_code.h#L61

Is it written anywhere r2 documentation that it uses this style? If it I am fine with that, but I haven't seen it used anywhere except r_annotated_code.

This https://github.com/radareorg/radare2/blob/master/DEVELOPERS.md claims that r2 uses doxygen C-style comments.

@ITAYC0HEN @thestr4ng3r I'm not sure when this was decided. See this comment by @ITAYC0HEN #16939 (review) It was discussed when I was working on #16939 .

Doxygen is the way to go.

karliss · 2020-08-03T11:44:11Z

 	}
 }

+R_API bool is_annotation_reference(RCodeAnnotation *annotation) {


Please consider renaming these functions. Most R_API functions use common prefix, this helps avoiding naming conflict and improves discoverability. Maybe r_annotation_is_reference and r_annotation_is_variable.

I will rename them.

@karliss I have renamed functions. If you are fine with the code now, please merge it. I think PR #2352 Cutter can get merged tonight. Since it uses the new API implemented in this PR, I want this to get merged first.

I will send a separate PR with documentation using Doxygen tonight, but I think it can be another PR as it could take more time to review.

ITAYC0HEN · 2020-08-03T13:07:36Z

+R_API bool r_annotation_is_reference(RCodeAnnotation *annotation);
+/**
+ * r_annotation_is_variable() - Checks if the specified annotation is a function variable.
+ * @annotation: Pointer to an annotation.


shouldn't it be @param annotation ?

This is how it is (if I understand correctly) in kernel-docs https://www.kernel.org/doc/html/v4.16/doc-guide/kernel-doc.html#how-to-format-kernel-doc-comments

ITAYC0HEN · 2020-08-03T13:08:50Z

+ */
+R_API bool r_annotation_is_reference(RCodeAnnotation *annotation);
+/**
+ * r_annotation_is_variable() - Checks if the specified annotation is a function variable.


Should you include the name of the function in the docs? "r_annotation_is_variable() "? Also, if you include this, the signature is wrong as it receive parameters

This is how it is in Kernel-doc, if I understand correctly. As I said, I'm going to update this to Doxygen, in another PR. So let's not worry about documentation for now.

ITAYC0HEN

Please make sure to fix the docs in the upcoming pr.

NirmalManoj · 2020-08-03T15:07:17Z

Here's the new PR fixing the documentation: #17397

radareorg#17386)

#17386)

…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)

NirmalManoj added 3 commits July 31, 2020 18:35

functions added

c8c81b2

formatted

6912ddd

add documentation

cfbaef6

NirmalManoj requested review from ret2libc, thestr4ng3r and trufae as code owners July 31, 2020 14:04

NirmalManoj requested review from ITAYC0HEN and karliss July 31, 2020 14:04

NirmalManoj added the API New API requests, changes, removal label Jul 31, 2020

NirmalManoj self-assigned this Jul 31, 2020

NirmalManoj mentioned this pull request Jul 31, 2020

X-Refs for references rizinorg/cutter#2352

Merged

3 tasks

karliss reviewed Jul 31, 2020

View reviewed changes

NirmalManoj requested a review from karliss July 31, 2020 14:47

NirmalManoj mentioned this pull request Aug 1, 2020

Edit/Rename Variables Actions for function variables rizinorg/cutter#2357

Merged

3 tasks

karliss reviewed Aug 3, 2020

View reviewed changes

renamed function as suggested

8097916

ITAYC0HEN reviewed Aug 3, 2020

View reviewed changes

ITAYC0HEN approved these changes Aug 3, 2020

View reviewed changes

ITAYC0HEN merged commit 2248961 into radareorg:decompiler-refactoring Aug 3, 2020

NirmalManoj added a commit to NirmalManoj/radare2 that referenced this pull request Aug 6, 2020

API for checking if an annotation is a reference or function variable. (

beaff91

radareorg#17386)

NirmalManoj added a commit that referenced this pull request Aug 9, 2020

API for checking if an annotation is a reference or function variable. (

cfc3ba9

#17386)

NirmalManoj mentioned this pull request Aug 9, 2020

New annotations and API functions for the decompiler #17429

Merged

3 tasks

Uh oh!

Uh oh!

Conversation

NirmalManoj commented Jul 31, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ITAYC0HEN left a comment

Choose a reason for hiding this comment

Uh oh!

NirmalManoj commented Aug 3, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants