Update docs in annotate code API (radareorg#17397)

libr/include/r_core.h

@@ -930,39 +930,34 @@ extern RCorePlugin r_core_plugin_a2f;
 
 /* DECOMPILER PRINTING FUNCTIONS */
 /**
-* r_core_annotated_code_print_json() - Prints the data contained in RAnnotatedCode *code in JSON format.
-* @code: Pointer to a RAnnotatedCode
-*
-* Prints the data contained in RAnnotatedCode represented by the pointer 'code' in JSON format. 
-* The function will print the output in console using the function r_cons_printf();
-* 	
-* Return: Nothing
-*/
+ * @brief Prints the data contained in the specified RAnnotatedCode in JSON format.
+ * 
+ * The function will print the output in console using the function r_cons_printf();
+ * 
+ * @param code Pointer to a RAnnotatedCode.
+ */
 R_API void r_core_annotated_code_print_json(RAnnotatedCode *code);
 /**
-* r_core_annotated_code_print() - Prints the decompiled code in the passed argument 'code'.
-* @code: Pointer to a RAnnotatedCode
-* @line_offsets: Pointer to a RVector that containes offsets for the decompiled code
-*
-* This function is used for printing the output of commands pdg and pdgo.
-* It can print the decompiled code with or without offsets. If line_offsets is a null pointer,
-* the output will be printed without offsets (pdg), otherwise, the output will be
-* printed with offsets.
-* This function will print the output in console using the function r_cons_printf();
-* 
-* Return: Nothing
-*/
+ * @brief Prints the decompiled code from the specified RAnnotatedCode.
+ * 
+ * This function is used for printing the output of commands pdg and pdgo.
+ * It can print the decompiled code with or without offsets. If line_offsets is a null pointer,
+ * the output will be printed without offsets (pdg), otherwise, the output will be
+ * printed with offsets.
+ * This function will print the output in console using the function r_cons_printf();
+ * 
+ * @param code Pointer to a RAnnotatedCode.
+ * @param line_offsets Pointer to a @ref RVector that contains offsets for the decompiled code.
+ */
 R_API void r_core_annotated_code_print(RAnnotatedCode *code, RVector *line_offsets);
 /**
-* r_core_annotated_code_print_comment_cmds() - Prints the decompiled code as comments
-* @code: Pointer to a RAnnotatedCode
-*
-* This functions prints the decompiled code as comment.
-* This function is used for the output of command pdg*
-* Output will be printed in console using the function r_cons_printf();
-* 	
-* Return: Nothing
-*/
+ * @brief  Prints the decompiled code as comments
+ * 
+ * This function is used for the output of command pdg*
+ * Output will be printed in console using the function r_cons_printf();
+ * 
+ * @param code Pointer to a RAnnotatedCode.
+ */
 R_API void r_core_annotated_code_print_comment_cmds(RAnnotatedCode *code);
 
 #endif

libr/include/r_util/r_annotated_code.h

@@ -21,48 +21,47 @@ typedef enum r_syntax_highlight_type_t {
 	R_SYNTAX_HIGHLIGHT_TYPE_GLOBAL_VARIABLE,
 } RSyntaxHighlightType;
 
-/**
- * enum r_code_annotation_type_t - typedefed as RCodeAnnotationType and this gives types of annotation
- *
- * There are two kinds of RCodeAnnotation. One for offset, which of the type 
- * R_CODE_ANNOTATION_TYPE_OFFSET and other one is for syntax highlight, which is
- * of the type R_CODE_ANNOTATION_TYPE_SYNTAX_HIGHLIGHT.
- * R_CODE_ANNOTATION_TYPE_OFFSET is for representing annotations that gives an offset for 
- * a range while R_CODE_ANNOTATION_TYPE_SYNTAX_HIGHLIGHT is for representing the
- * kind of data the range represents. Here, range refers to the range of annotation.
- */
-
+/** Represents the type of annnotation. */
 typedef enum r_code_annotation_type_t {
-	R_CODE_ANNOTATION_TYPE_OFFSET,
-	R_CODE_ANNOTATION_TYPE_SYNTAX_HIGHLIGHT,
-	R_CODE_ANNOTATION_TYPE_FUNCTION_NAME,
-	R_CODE_ANNOTATION_TYPE_GLOBAL_VARIABLE,
-	R_CODE_ANNOTATION_TYPE_CONSTANT_VARIABLE,
-	R_CODE_ANNOTATION_TYPE_LOCAL_VARIABLE,
-	R_CODE_ANNOTATION_TYPE_FUNCTION_PARAMETER,
+	R_CODE_ANNOTATION_TYPE_OFFSET, /*!< Gives the offset of the specified range in annotation. */ 
+	R_CODE_ANNOTATION_TYPE_SYNTAX_HIGHLIGHT, /*!< Represents the kind of data the specified range represents for highlighting purposes. */ 
+	R_CODE_ANNOTATION_TYPE_FUNCTION_NAME, /*!< Specified range in annotation represents a function name. */ 
+	R_CODE_ANNOTATION_TYPE_GLOBAL_VARIABLE, /*!< Specified range in annotation represents a global variable. */ 
+	R_CODE_ANNOTATION_TYPE_CONSTANT_VARIABLE, /*!< Specified range in annotation represents a constant variable with an address. */ 
+	R_CODE_ANNOTATION_TYPE_LOCAL_VARIABLE, /*!< Specified range in annotation represents a local variable. */ 
+	R_CODE_ANNOTATION_TYPE_FUNCTION_PARAMETER, /*!< Specified range in annotation represents a function parameter. */ 
 	// ...
 } RCodeAnnotationType;
 
+/**
+ * \brief Annotations for the decompiled code are represented using this structure.
+ */
 typedef struct r_code_annotation_t {
-	size_t start;
-	size_t end;
+	size_t start; /**< Start of the range in the annotation(inclusive). */ 
+	size_t end; /**< End of the range in the annotation(exclusive). */ 
 	RCodeAnnotationType type;
 	union {
+		/** If the annotation is of type R_CODE_ANNOTATION_TYPE_OFFSET,
+		 * offset should be stored in the struct named offset in this union.
+		 */
 		struct {
 			ut64 offset;
 		} offset;
-
+		/** If the annotation is of type R_CODE_ANNOTATION_TYPE_SYNTAX_HIGHLIGHT,
+		 * type of the syntax highlight will be stored in the struct named syntax_highlight
+		 * in this union.
+		 */
 		struct {
 			RSyntaxHighlightType type;
 		} syntax_highlight;
 
 		/** Information in annotations of type R_CODE_ANNOTATION_TYPE_FUNCTION_NAME,
 		 * R_CODE_ANNOTATION_TYPE_GLOBAL_VARIABLE, and R_CODE_ANNOTATION_TYPE_CONSTANT_VARIABLE
-		 * will be stored in the struct name reference in this union.
+		 * will be stored in the struct named reference in this union.
 		 */
 		struct {
 			char *name;
-			ut64 offset; // address
+			ut64 offset;
 		} reference;
 
 		/** Information in annotations of type R_CODE_ANNOTATION_TYPE_LOCAL_VARIABLE
@@ -74,110 +73,103 @@ typedef struct r_code_annotation_t {
 		} variable;
 	};
 } RCodeAnnotation;
-
+/**
+ * \brief This structure contains the decompiled code and all the annotations for the decompiled code.
+ */
 typedef struct r_annotated_code_t {
-	char *code; // owned
-	RVector /*<RCodeAnnotation>*/ annotations;
+	char *code; /**< Decompiled code. RAnnotatedCode owns this string and it must free it. */ 
+	RVector annotations; /**< @ref RVector <RCodeAnnotation> contains the list of annotations for the decompiled code. */ 
 } RAnnotatedCode;
 
 /**
- * r_annotated_code_new() - Creates a new RAnnotatedCode structure and returns its pointer.
- * @code: Literal code for which the RAnnotatedCode structure will be created .
- *
- * This functions creates a new RAnnotatedCode structure.
- * RAnnotatedCode.code will be initialized as the character array passed.
- * Here, code must be a string that can deallocated.
- * This will initialize RVector<RCodeAnnotation> annotations as well.
- * 
- * Return: Pointer to the new RAnnotatedCode structure created.
+ * @brief Create and initialize a RAnnotatedCode structure and returns its pointer.
+ * 
+ * This function creates and initializes a new RAnnotatedCode
+ * structure with the specified decompiled code that's passed
+ * as an argument. Here, the argument code must be a string that can be deallocated.
+ * This will initialize @ref RVector <RCodeAnnotation> annotations as well.
+ * 
+ * @param code A deallocatable character array.
+ * @return Pointer to the new RAnnotatedCode structure created.
  */
 R_API RAnnotatedCode *r_annotated_code_new(char *code);
 /**
- * r_annotated_code_free() - Deallocates *code.
- * @code: Pointer to a RAnnotatedCode.
- *
- * This functions deallocates memory allocated for *code.
+ * @brief Deallocates the dynamically allocated memory for the specified RAnnotatedCode.
  * 
- * Return: Nothing.
+ * @param code Pointer to a RAnnotatedCode.
  */
 R_API void r_annotated_code_free(RAnnotatedCode *code);
 /**
- * r_annotation_free() - Deallocates dynamically allocated memory for the specified annotation.
- * @e: Pointer to the annotation
- * @user: Always NULL for this function. Present here for this function to be of the type RVectorFree.
+ * @brief Deallocates dynamically allocated memory for the specified annotation.
  * 
  * This function recognizes the type of the specified annotation and
  * frees memory that is dynamically allocated for it.
  * 
- * Return: Nothing.
+ * @param e Pointer to the annotation.
+ * @param user Always NULL for this function. Present here for this function to be of the type @ref RVectorFree.
  */
 R_API void r_annotation_free(void *e, void *user);
 /**
- * r_annotation_is_reference() - Checks if the specified annotation is a reference.
- * @annotation: Pointer to an annotation.
+ * @brief Checks if the specified annotation is a reference.
  * 
  * 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.
+ * @param annotation Pointer to an annotation.
+ * @return Returns true if the specified annotation is a reference.
  */
 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.
+ * @brief Checks if the specified annotation is a function variable.
  * 
  * 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.
+ * @param annotation Pointer to an annotation.
+ * @return Returns true if the specified annotation is a function variable.
  */
 R_API bool r_annotation_is_variable(RCodeAnnotation *annotation);
 /**
- * r_annotated_code_add_annotation() - Inserts *annotation in *code.
- * @code: Pointer to a RAnnotatedCode.
- * @annotation: Pointer to a annotation.
- *
- * This functions inserts the annotation represented by the pointer 'annotation' to the vector
- * of annotations in the RAnnotatedCode represented by 'code'. To be more precise,
- * annotation will be added to code->annotations, which is a RVector<RCodeAnnotation> annotations.
- * 
- * Return: Nothing.
+ * @brief Inserts the specified annotation into the list of annotations in the specified RAnnotatedCode.
+ * 
+ * @param code Pointer to a RAnnotatedCode.
+ * @param annotation Pointer to an annotation.
  */
 R_API void r_annotated_code_add_annotation(RAnnotatedCode *code, RCodeAnnotation *annotation);
 /**
- * r_annotated_code_annotations_in() - Returns all annotations with range that contains the given offset.
- * @code: Pointer to a RAnnotatedCode.
- * @offset: Offset.
- *
- * Creates an RPVector and inserts the pointers to all annotations in which 
+ * @brief Returns all annotations with range that contains the given offset.
+ * 
+ * Creates a @ref RPVector <RCodeAnnotation> and inserts the pointers to all annotations in which 
  * annotation->start <= offset < annotation->end.
  * 
- * Return: Pointer to the RPVecrtor created.
+ * @param code Pointer to a RAnnotatedCode.
+ * @param offset Offset.
+ * @return Pointer to the @ref RPVector created.
  */
 R_API RPVector *r_annotated_code_annotations_in(RAnnotatedCode *code, size_t offset);
 /**
- * r_annotated_code_annotations_range() - Returns all annotations with range that overlap with the given range.
- * @code: Pointer to a RAnnotatedCode.
- * @start: Start of the range(inclusive).
- * @end: End of the range(exclusive).
- *
- * Creates an RPVector and inserts the pointers to all annotations whose 
- * range overlap with range [start, end-1] (both inclusive).
- * 
- * Return: Pointer to the RPVecrtor created.
+ * @brief Returns all annotations with range that overlap with the specified range.
+ * 
+ * Creates an @ref RPVector <RCodeAnnotation> and inserts the pointers to all annotations whose 
+ * range overlap with range specified.
+ * 
+ * @param code Pointer to a RAnnotatedCode.
+ * @param start Start of the range(inclusive).
+ * @param end End of the range(exclusive).
+ * @return Pointer to the @ref RPVector created.
  */
 R_API RPVector *r_annotated_code_annotations_range(RAnnotatedCode *code, size_t start, size_t end);
 /**
- * r_annotated_code_line_offsets() - Returns the offset for every line of decompiled code in RAnnotatedCode *code.
- * @code: Pointer to a RAnnotatedCode.
- *
- * Creates an RVector and inserts the offsets for every seperate line of decompiled code in
- * code->code (code->code is a character array).
+ * @brief Returns the offset for every line of decompiled code in the specified RAnnotatedCode.
+ * 
+ * Creates an @ref RVector <ut64> and inserts the offsets for every seperate line of decompiled code in
+ * the specified RAnnotatedCode.
  * If a line of decompiled code doesn't have a unique offset, UT64_MAX is inserted as its offset.
- * 	
- * Return: Pointer to the RVector created.
+ * 
+ * @param code Pointer to a RAnnotatedCode.
+ * @return Pointer to the @ref RVector created.
  */
 R_API RVector *r_annotated_code_line_offsets(RAnnotatedCode *code);