doxygen:overloaded function - chunhualiao/public-docs GitHub Wiki

http://rosecompiler.org/ROSE_HTML_Reference/namespaceSageInterface.html

Correct behavior


std::string | get_name (const SgNode *node)
-- | --
  | Generate a useful name to describe the SgNode.
 
std::string | get_name (const SgStatement *stmt)
  | Generate a useful name to describe the declaration.

std::string 	[get_name](http://rosecompiler.org/ROSE_HTML_Reference/namespaceSageInterface.html#acbd105615b111c43782054ffad047560) (const [SgNode](http://rosecompiler.org/ROSE_HTML_Reference/classSgNode.html) *node)
 	Generate a useful name to describe the [SgNode](http://rosecompiler.org/ROSE_HTML_Reference/classSgNode.html).
 
std::string 	[get_name](http://rosecompiler.org/ROSE_HTML_Reference/namespaceSageInterface.html#a3dac77c387a779e408064c33a49463a7) (const [SgStatement](http://rosecompiler.org/ROSE_HTML_Reference/classSgStatement.html) *stmt)
 	Generate a useful name to describe the declaration.

When documenting overloaded functions in Doxygen, it is important to ensure that each overload is clearly distinguished while still maintaining a cohesive documentation structure. Here’s how to properly document overloaded functions like SageInterface::get_name for both SgNode and SgStatement:

Correct Way to Document Overloaded Functions

  1. Separate Documentation Blocks: Each overloaded function should have its own documentation block. This allows you to provide specific details relevant to each overload.

  2. Use @overload Tag: You can use the @overload tag to indicate that the function is an overload of another function. This helps Doxygen understand the relationship between the overloads.

  3. Consistent Naming: Ensure that the function signatures are consistent in the documentation to avoid confusion.

Example Documentation

Here’s how you can document the overloaded get_name functions:

/**
 * @brief Returns a string representation of the given IR node.
 *
 * This function is useful for debugging purposes. It provides a generic way to obtain
 * a name or identifier for any SgNode object in the ROSE AST. The actual name returned
 * depends on the specific type of node being queried, and may be derived from various
 * attributes such as symbol names, token values, or class names.
 *
 * @param node The IR node for which to retrieve a string representation.
 *             Must be non-null; behavior is undefined if null.
 *
 * @return A string identifier for the given node. If no specific name can be determined,
 *         returns "undefined_name".
 *
 * @warning This function may not always return a unique or meaningful result, especially
 *          for nodes that do not have an inherent name or identifier (e.g., certain types
 *          of statements). Use with caution.
 *
 * @pre The input node must be non-null.
 *
 * @post The returned string is guaranteed to be non-empty and may contain spaces.
 *
 * @note This function uses a recursive approach to handle different types of nodes,
 *       which may lead to performance issues for very large ASTs. However, it provides
 *       a general solution that can be applied to any SgNode object.
 *
 * @example This example demonstrates how to use this function:
 *          \code
 *           const SgNode* node = ...; // assume some IR node is created or retrieved
 *           string nodeName = get_name(node);
 *           cout << "Node name: " << nodeName << endl;
 *          \endcode
 */
string SageInterface::get_name(const SgNode* node);

/**
 * @brief Retrieves the name of a given statement.
 *
 * This function determines the name of a statement based on its type. If the
 * statement is a declaration, it uses the get_name() function for declarations.
 * Otherwise, it checks if the statement is a scope and uses the get_name()
 * function for scopes if applicable. For other types of statements, it uses
 * a switch-case block to handle different variants of statements.
 *
 * @param stmt The statement for which the name is to be retrieved.
 *             Must not be NULL (enforced by ROSE_ASSERT).
 *
 * @return The name of the input statement as a string. If the type of statement
 *         does not have an associated name, it returns the class_name() of
 *         the statement instead.
 *
 * @warning This function assumes that the input statement is valid and can be
 *          safely cast to different types of statements based on its variantT().
 *          It also relies on the get_name() functions for declarations and scopes
 *          to return correct results. If these assumptions are not met, incorrect
 *          names may be returned or assertions may fail.
 *
 * @pre The input statement must not be NULL.
 *
 * @post The function will return a string representing the name of the statement.
 *
 * @note This function uses ROSE_ASSERT to enforce its precondition and relies on
 *       other functions (get_name() for declarations and scopes) to work correctly.
 *
 * @example This example demonstrates how to use this function:
 *          \code
 *            SgStatement* stmt = ...; // assume stmt is initialized properly
 *            string name = SageInterface::get_name(stmt);
 *            cout << "Name of statement: " << name << endl;
 *          \endcode
 */
string SageInterface::get_name(const SgStatement* stmt);

Key Points

  • Separate Blocks: Each overload has its own documentation block, which allows for specific details about each function.
  • Clear Parameters and Return Values: Each block clearly states the parameters and return values relevant to that specific overload.
  • Examples: Each overload can have its own example, demonstrating how to use that specific function.

Conclusion

By following this structure, you ensure that your documentation is clear, organized, and informative for users of your API. This approach will help avoid warnings related to duplicate documentation and improve the overall quality of your Doxygen output. If you have any further questions or need additional assistance, feel free to ask!