[NFC][Docs] Add missing Doxygen group comments for LLVM-C

[supergrecko]

Summary

The LLVM-C API is relatively small, so we've previously added doxygen group tags
so it's easy to navigate LLVM-C on the web documentation. Over the years, more
LLVM-C headers have been added without the doxygen tags, effectively hiding
them from the "LLVM-C: C Interface to LLVM" doxygen page.

This patch adds doxygen group comments to the headers which did not have them
previously. The new items added to the doxygen group tree looks like this:

|-- LLVM-C
  + Linker (Linker.h)
  + Error Handling (Error.h, ErrorHandling.h)
  |-- Core
    + Comdats (Comdat.h)
    + Debug Information (DebugInfo.h)
    + New Pass Manager (Transforms/PassBuilder.h)
    + IR Reader (IRReader.h)
    + Pass Registry (moved from root)
    + Pass Manager (moved from root)
  |-- Execution Engine
    + Executon Engine LLJIT (LLJIT.h)
    + On-Request-Compilation (Orc.h)
    + ORC Execution (OrcEE.h)
  - Pass Registry
  - Pass Manager

The groups Pass Registry and PassManager have been moved into LLVMCCore as their
names hinted. (LLVMCCorePassRegistry and LLVMCCorePassManager) I believe the
original author forgot the doxygen ingroup directive which is why they were
misplaced at root.

In addition to this, the following groups have been updated:

• Core (Support.h has been added to the group)
• Disassembler (DisassemblerTypes.h has been added to the group)
• Target information (TargetMachine.h has been added to the group)

[lhames]

This is a nice change -- thanks @supergrecko!

+ Executon Engine LLJIT (LLJIT.h)
+ On-Request-Compilation (Orc.h)
+ ORC Execution (OrcEE.h)

These should be changed to just "LLJIT (LLJIT.h)" and "ExecutionEngine-based ORC Utils (OrcEE.h)".

Otherwise LGTM.

[supergrecko]

Rename LLJIT and OrcEE header doxygen groups

Addressing review comments:

Execution Engine LLJIT -> LLJIT
ORC Execution -> ExecutionEngine-based ORC Utils

[supergrecko]

Rename LLJIT and OrcEE header doxygen groups

Addressing review comments:

Execution Engine LLJIT -> LLJIT
ORC Execution -> ExecutionEngine-based ORC Utils

llvm/include/llvm-c/Comdat.h

 #ifndef LLVM_C_COMDAT_H
 #define LLVM_C_COMDAT_H
 
 #include "llvm-c/ExternC.h"
 #include "llvm-c/Types.h"
 
 LLVM_C_EXTERN_C_BEGIN
 
+/**
+ * @defgroup LLVMCCoreComdat Comdats
+ * @ingroup LLVMCCore
+ *
+ * @{
+ */
+
 typedef enum {
   LLVMAnyComdatSelectionKind,        ///< The linker may choose any COMDAT.
   LLVMExactMatchComdatSelectionKind, ///< The data referenced by the COMDAT must
                                      ///< be the same.
   LLVMLargestComdatSelectionKind,    ///< The linker will choose the largest
                                      ///< COMDAT.
   LLVMNoDeduplicateComdatSelectionKind, ///< No deduplication is performed.
   LLVMSameSizeComdatSelectionKind ///< The data referenced by the COMDAT must be

 
 /*
  * Set the conflict resolution selection kind for the Comdat.
  *
  * @see llvm::Comdat::setSelectionKind()
  */
 void LLVMSetComdatSelectionKind(LLVMComdatRef C, LLVMComdatSelectionKind Kind);
 
+/**
+ * @}
+ */
+
 LLVM_C_EXTERN_C_END
 
 #endif

llvm/include/llvm-c/Core.h

 void LLVMDisposeMemoryBuffer(LLVMMemoryBufferRef MemBuf);
 
 /**
  * @}
  */
 
 /**
  * @defgroup LLVMCCorePassRegistry Pass Registry
+ * @ingroup LLVMCCore
  *
  * @{
  */
 
 /** Return the global pass registry, for use with initialization functions.
     @see llvm::PassRegistry::getPassRegistry */
 LLVMPassRegistryRef LLVMGetGlobalPassRegistry(void);
 
 /**
  * @}
  */
 
 /**
  * @defgroup LLVMCCorePassManagers Pass Managers
+ * @ingroup LLVMCCore
  *
  * @{
  */
 
 /** Constructs a new whole-module pass pipeline. This type of pipeline is
     suitable for link-time optimization and whole-module transformations.
     @see llvm::PassManager::PassManager */
 LLVMPassManagerRef LLVMCreatePassManager(void);

llvm/include/llvm-c/DebugInfo.h

 #define LLVM_C_DEBUGINFO_H
 
 #include "llvm-c/Core.h"
 #include "llvm-c/ExternC.h"
 
 LLVM_C_EXTERN_C_BEGIN
 
 /**
+ * @defgroup LLVMCCoreDebugInfo Debug Information
+ * @ingroup LLVMCCore
+ *
+ * @{
+ */
+
+/**
  * Debug info flags.
  */
 typedef enum {
   LLVMDIFlagZero = 0,
   LLVMDIFlagPrivate = 1,
   LLVMDIFlagProtected = 2,
   LLVMDIFlagPublic = 3,
   LLVMDIFlagFwdDecl = 1 << 2,

 
 /**
  * Obtain the enumerated type of a Metadata instance.
  *
  * @see llvm::Metadata::getMetadataID()
  */
 LLVMMetadataKind LLVMGetMetadataKind(LLVMMetadataRef Metadata);
 
+/**
+ * @}
+ */
+
 LLVM_C_EXTERN_C_END
 
 #endif

llvm/include/llvm-c/DisassemblerTypes.h

 #include "llvm-c/DataTypes.h"
 #ifdef __cplusplus
 #include <cstddef>
 #else
 #include <stddef.h>
 #endif
 
 /**
+ * @addtogroup LLVMCDisassembler
+ *
+ * @{
+ */
+
+/**
  * An opaque reference to a disassembler context.
  */
 typedef void *LLVMDisasmContextRef;
 
 /**
  * The type for the operand information call back function.  This is called to
  * get the symbolic information for an operand of an instruction.  Typically
  * this is from the relocation information, symbol table, etc.  That block of

 /* The output reference is to a Objective-C selector ref. */
 #define LLVMDisassembler_ReferenceType_Out_Objc_Selector_Ref 7
 /* The output reference is to a Objective-C class ref. */
 #define LLVMDisassembler_ReferenceType_Out_Objc_Class_Ref 8
 
 /* The output reference is to a C++ symbol name. */
 #define LLVMDisassembler_ReferenceType_DeMangled_Name 9
 
+/**
+ * @}
+ */
+
 #endif

llvm/include/llvm-c/Error.h

 
 #ifndef LLVM_C_ERROR_H
 #define LLVM_C_ERROR_H
 
 #include "llvm-c/ExternC.h"
 
 LLVM_C_EXTERN_C_BEGIN
 
+/**
+ * @defgroup LLVMCError Error Handling
+ * @ingroup LLVMC
+ *
+ * @{
+ */
+
 #define LLVMErrorSuccess 0
 
 /**
  * Opaque reference to an error instance. Null serves as the 'success' value.
  */
 typedef struct LLVMOpaqueError *LLVMErrorRef;
 
 /**

  */
 LLVMErrorTypeId LLVMGetStringErrorTypeId(void);
 
 /**
  * Create a StringError.
  */
 LLVMErrorRef LLVMCreateStringError(const char *ErrMsg);
 
+/**
+ * @}
+ */
+
 LLVM_C_EXTERN_C_END
 
 #endif

llvm/include/llvm-c/ErrorHandling.h

 
 #ifndef LLVM_C_ERRORHANDLING_H
 #define LLVM_C_ERRORHANDLING_H
 
 #include "llvm-c/ExternC.h"
 
 LLVM_C_EXTERN_C_BEGIN
 
+/**
+ * @addtogroup LLVMCError
+ *
+ * @{
+ */
+
 typedef void (*LLVMFatalErrorHandler)(const char *Reason);
 
 /**
  * Install a fatal error handler. By default, if LLVM detects a fatal error, it
  * will call exit(1). This may not be appropriate in many contexts. For example,
  * doing exit(1) will bypass many crash reporting/tracing system tools. This
  * function allows you to install a callback that will be invoked prior to the
  * call to exit(1).
  */
 void LLVMInstallFatalErrorHandler(LLVMFatalErrorHandler Handler);
 
 /**
  * Reset the fatal error handler. This resets LLVM's fatal error handling
  * behavior to the default.
  */
 void LLVMResetFatalErrorHandler(void);
 
 /**
  * Enable LLVM's built-in stack trace code. This intercepts the OS's crash
  * signals and prints which component of LLVM you were in at the time if the
  * crash.
  */
 void LLVMEnablePrettyStackTrace(void);
 
+/**
+ * @}
+ */
+
 LLVM_C_EXTERN_C_END
 
 #endif

llvm/include/llvm-c/IRReader.h

 #define LLVM_C_IRREADER_H
 
 #include "llvm-c/ExternC.h"
 #include "llvm-c/Types.h"
 
 LLVM_C_EXTERN_C_BEGIN
 
 /**
+ * @defgroup LLVMCCoreIRReader IR Reader
+ * @ingroup LLVMCCore
+ *
+ * @{
+ */
+
+/**
  * Read LLVM IR from a memory buffer and convert it into an in-memory Module
  * object. Returns 0 on success.
  * Optionally returns a human-readable description of any errors that
  * occurred during parsing IR. OutMessage must be disposed with
  * LLVMDisposeMessage.
  *
  * @see llvm::ParseIR()
  */
 LLVMBool LLVMParseIRInContext(LLVMContextRef ContextRef,
                               LLVMMemoryBufferRef MemBuf, LLVMModuleRef *OutM,
                               char **OutMessage);
 
+/**
+ * @}
+ */
+
 LLVM_C_EXTERN_C_END
 
 #endif

llvm/include/llvm-c/LLJIT.h

 #include "llvm-c/Error.h"
 #include "llvm-c/Orc.h"
 #include "llvm-c/TargetMachine.h"
 #include "llvm-c/Types.h"
 
 LLVM_C_EXTERN_C_BEGIN
 
 /**
+ * @defgroup LLVMCExecutionEngineLLJIT LLJIT
+ * @ingroup LLVMCExecutionEngine
+ *
+ * @{
+ */
+
+/**
  * A function for constructing an ObjectLinkingLayer instance to be used
  * by an LLJIT instance.
  *
  * Clients can call LLVMOrcLLJITBuilderSetObjectLinkingLayerCreator to
  * set the creator function to use when constructing an LLJIT instance.
  * This can be used to override the default linking layer implementation
  * that would otherwise be chosen by LLJITBuilder.
  *

 /**
  * Get the LLJIT instance's default data layout string.
  *
  * This string is owned by the LLJIT instance and does not need to be freed
  * by the caller.
  */
 const char *LLVMOrcLLJITGetDataLayoutStr(LLVMOrcLLJITRef J);
 
+/**
+ * @}
+ */
+
 LLVM_C_EXTERN_C_END
 
 #endif /* LLVM_C_LLJIT_H */

llvm/include/llvm-c/Linker.h

 #ifndef LLVM_C_LINKER_H
 #define LLVM_C_LINKER_H
 
 #include "llvm-c/ExternC.h"
 #include "llvm-c/Types.h"
 
 LLVM_C_EXTERN_C_BEGIN
 
+/**
+ * @defgroup LLVMCCoreLinker Linker
+ * @ingroup LLVMCCore
+ *
+ * @{
+ */
+
 /* This enum is provided for backwards-compatibility only. It has no effect. */
 typedef enum {
   LLVMLinkerDestroySource = 0, /* This is the default behavior. */
   LLVMLinkerPreserveSource_Removed = 1 /* This option has been deprecated and
                                           should not be used. */
 } LLVMLinkerMode;
 
 /* Links the source module into the destination module. The source module is
  * destroyed.
  * The return value is true if an error occurred, false otherwise.
  * Use the diagnostic handler to get any diagnostic message.
 */
 LLVMBool LLVMLinkModules2(LLVMModuleRef Dest, LLVMModuleRef Src);
 
 LLVM_C_EXTERN_C_END
 
+/**
+ * @}
+ */
+
 #endif

llvm/include/llvm-c/Orc.h

 
 #include "llvm-c/Error.h"
 #include "llvm-c/TargetMachine.h"
 #include "llvm-c/Types.h"
 
 LLVM_C_EXTERN_C_BEGIN
 
 /**
+ * @defgroup LLVMCExecutionEngineORC On-Request-Compilation
+ * @ingroup LLVMCExecutionEngine
+ *
+ * @{
+ */
+
+/**
  * Represents an address in the executor process.
  */
 typedef uint64_t LLVMOrcJITTargetAddress;
 
 /**
  * Represents an address in the executor process.
  */
 typedef uint64_t LLVMOrcExecutorAddress;

 void LLVMOrcDisposeDumpObjects(LLVMOrcDumpObjectsRef DumpObjects);
 
 /**
  * Dump the contents of the given MemoryBuffer.
  */
 LLVMErrorRef LLVMOrcDumpObjects_CallOperator(LLVMOrcDumpObjectsRef DumpObjects,
                                              LLVMMemoryBufferRef *ObjBuffer);
 
+/**
+ * @}
+ */
+
 LLVM_C_EXTERN_C_END
 
 #endif /* LLVM_C_ORC_H */

llvm/include/llvm-c/OrcEE.h

 #include "llvm-c/ExecutionEngine.h"
 #include "llvm-c/Orc.h"
 #include "llvm-c/TargetMachine.h"
 #include "llvm-c/Types.h"
 
 LLVM_C_EXTERN_C_BEGIN
 
 /**
+ * @defgroup LLVMCExecutionEngineORCEE ExecutionEngine-based ORC Utils
+ * @ingroup LLVMCExecutionEngine
+ *
+ * @{
+ */
+
+/**
  * Create a RTDyldObjectLinkingLayer instance using the standard
  * SectionMemoryManager for memory management.
  */
 LLVMOrcObjectLayerRef
 LLVMOrcCreateRTDyldObjectLinkingLayerWithSectionMemoryManager(
     LLVMOrcExecutionSessionRef ES);
 
 /**
  * Add the given listener to the given RTDyldObjectLinkingLayer.
  *
  * Note: Layer must be an RTDyldObjectLinkingLayer instance or
  * behavior is undefined.
  */
 void LLVMOrcRTDyldObjectLinkingLayerRegisterJITEventListener(
     LLVMOrcObjectLayerRef RTDyldObjLinkingLayer,
     LLVMJITEventListenerRef Listener);
 
+/**
+ * @}
+ */
+
 LLVM_C_EXTERN_C_END
 
 #endif /* LLVM_C_ORCEE_H */

llvm/include/llvm-c/Support.h

 
 #include "llvm-c/DataTypes.h"
 #include "llvm-c/ExternC.h"
 #include "llvm-c/Types.h"
 
 LLVM_C_EXTERN_C_BEGIN
 
 /**
+ * @addtogroup LLVMCCore
+ *
+ * @{
+ */
+
+/**
  * This function permanently loads the dynamic library at the given path.
  * It is safe to call this function multiple times for the same library.
  *
  * @see sys::DynamicLibrary::LoadLibraryPermanently()
   */
 LLVMBool LLVMLoadLibraryPermanently(const char* Filename);
 
 /**

  * This functions permanently adds the symbol \p symbolName with the
  * value \p symbolValue.  These symbols are searched before any
  * libraries.
  *
  * @see sys::DynamicLibrary::AddSymbol()
  */
 void LLVMAddSymbol(const char *symbolName, void *symbolValue);
 
+/**
+ * @}
+ */
+
 LLVM_C_EXTERN_C_END
 
 #endif

llvm/include/llvm-c/TargetMachine.h

 #define LLVM_C_TARGETMACHINE_H
 
 #include "llvm-c/ExternC.h"
 #include "llvm-c/Target.h"
 #include "llvm-c/Types.h"
 
 LLVM_C_EXTERN_C_BEGIN
 
+/**
+ * @addtogroup LLVMCTarget
+ *
+ * @{
+ */
+
 typedef struct LLVMOpaqueTargetMachine *LLVMTargetMachineRef;
 typedef struct LLVMTarget *LLVMTargetRef;
 
 typedef enum {
     LLVMCodeGenLevelNone,
     LLVMCodeGenLevelLess,
     LLVMCodeGenLevelDefault,
     LLVMCodeGenLevelAggressive

 
 /** Get the host CPU's features as a string. The result needs to be disposed
   with LLVMDisposeMessage. */
 char* LLVMGetHostCPUFeatures(void);
 
 /** Adds the target-specific analysis passes to the pass manager. */
 void LLVMAddAnalysisPasses(LLVMTargetMachineRef T, LLVMPassManagerRef PM);
 
+/**
+ * @}
+ */
+
 LLVM_C_EXTERN_C_END
 
 #endif

llvm/include/llvm-c/Transforms/PassBuilder.h

 
 #ifndef LLVM_C_TRANSFORMS_PASSBUILDER_H
 #define LLVM_C_TRANSFORMS_PASSBUILDER_H
 
 #include "llvm-c/Error.h"
 #include "llvm-c/TargetMachine.h"
 #include "llvm-c/Types.h"
 
+/**
+ * @defgroup LLVMCCoreNewPM New Pass Manager
+ * @ingroup LLVMCCore
+ *
+ * @{
+ */
+
 LLVM_C_EXTERN_C_BEGIN
 
 /**
  * A set of options passed which are attached to the Pass Manager upon run.
  *
  * This corresponds to an llvm::LLVMPassBuilderOptions instance
  *
  * The details for how the different properties of this structure are used can

 void LLVMPassBuilderOptionsSetMergeFunctions(LLVMPassBuilderOptionsRef Options,
                                              LLVMBool MergeFunctions);
 
 /**
  * Dispose of a heap-allocated PassBuilderOptions instance
  */
 void LLVMDisposePassBuilderOptions(LLVMPassBuilderOptionsRef Options);
 
+/**
+ * @}
+ */
+
 LLVM_C_EXTERN_C_END
 
 #endif // LLVM_C_TRANSFORMS_PASSBUILDER_H