added documentation to VXInstructionFormatterC.h

Bindings/C/VXInstructionDecoderC.h

@@ -125,7 +125,7 @@ bool VXBaseDataSource_SetPosition(
  * @brief   Creates a memory data source.
  * @param   buffer      The input buffer.
  * @param   bufferLen   THe length of the input buffer.
- * @return  @c nullptr if it fails, else a data source context.
+ * @return  @c NULL if it fails, else a data source context.
  * @see     VXBaseDataSource_Release
  */
 // TODO: verify return value
@@ -161,7 +161,7 @@ typedef struct _VXInstructionDecoderContext { int a; } VXInstructionDecoderConte
 
 /**
  * @brief   Creates an instruction decoder.
- * @return  @c nullptr if it fails, else an instruction decoder context.
+ * @return  @c NULL if it fails, else an instruction decoder context.
  * @see     VXInstructionDecoder_Release
  */
 // TODO: verify return value
@@ -173,7 +173,7 @@ VXInstructionDecoderContext* VXInstructionDecoder_Create(void);
  * @param   disassemblerMode    The disassembler mode.
  * @param   preferredVendor     The preferred instruction-set vendor.
  * @param   instructionPointer  The initial instruction pointer.
- * @return  @c nullptr if it fails, else an instruction decoder context.
+ * @return  @c NULL if it fails, else an instruction decoder context.
  * @see     VXInstructionDecoder_Release
  */
 VXInstructionDecoderContext* VXInstructionDecoder_CreateEx(

Bindings/C/VXInstructionFormatterC.cpp

@@ -152,11 +152,6 @@ inline const VXBaseInstructionFormatterContext* VXIntelInstructionFormatter_CPtr
 
 /* VXBaseSymbolResolver ======================================================================== */
 
-VXBaseSymbolResolverContext* VXBaseSymbolResolver_Create()
-{
-    return VXBaseSymbolResolver_CPtr(new Verteron::VXBaseSymbolResolver);
-}
-
 void VXBaseSymbolResolver_Release(
     VXBaseSymbolResolverContext *ctx)
 {

Bindings/C/VXInstructionFormatterC.h

@@ -42,13 +42,25 @@ extern "C"
 
 /* VXBaseSymbolResolver ======================================================================== */
 
-    typedef struct _VXBaseSymbolResolverContext { int a; } VXBaseSymbolResolverContext;
+typedef struct _VXBaseSymbolResolverContext { int a; } VXBaseSymbolResolverContext;
-
-VXBaseSymbolResolverContext* VXBaseSymbolResolver_Create(void);
 
+/**
+ * @brief   Releases a symbol resolver.
+ * @param   ctx The context of the symbol resolver to free.
+ * The context may no longer used after it was released.
+ */
 void VXBaseSymbolResolver_Release(
     VXBaseSymbolResolverContext *ctx);
 
+/**
+ * @brief   Resolves a symbol.
+ * @param   ctx     The symbol resolver context.
+ * @param   info    The instruction info.
+ * @param   address The address.
+ * @param   offset  Pointer to an unsigned 64 bit integer that receives an offset relative to 
+ *                  the base address of the symbol.
+ * @return  The name of the symbol if the symbol was found, else @c NULL.
+ */
 const char* VXBaseSymbolResolver_ResolveSymbol(
     VXBaseSymbolResolverContext *ctx,
     const VXInstructionInfo *info, 
@@ -57,21 +69,50 @@ const char* VXBaseSymbolResolver_ResolveSymbol(
 
 /* VXExactSymbolResolver ======================================================================= */
 
+/**
+ * @brief   Creates an exact symbol resolver.
+ * @return  @c NULL if it fails, else a symbol resolver context.
+ * @see     VXBaseSymbolResolver_Release
+ * An exact resolver is a simple symbol resolver that only matches exact addresses.
+ */
+// TODO: verify return value
 VXBaseSymbolResolverContext* VXExactSymbolResolver_Create(void);
 
+/**
+ * @brief   Query if the given address is a known symbol.
+ * @param   ctx     The exact symbol resolver context.
+ * @param   address The address.
+ * @return  @c true if the address is known, @c false if not.
+ */
 bool VXExactSymbolResolver_ContainsSymbol(
     VXBaseSymbolResolverContext *ctx,
     uint64_t address);
 
+/**
+ * @brief   Adds or changes a symbol.
+ * @param   ctx     The exact symbol resolver context.
+ * @param   address The address.
+ * @param   name    The symbol name.
+ */
 void VXExactSymbolResolverContext_SetSymbol(
     VXBaseSymbolResolverContext *ctx,
     uint64_t address, 
     const char* name);
 
+/**
+ * @brief   Removes the symbol described by address.
+ * @param   ctx     The exact symbol resolver context.
+ * @param   address The address.
+ * This will invalidate all char-pointers to the affected symbol name.
+ */
 void VXExactSymbolResolverContext_RemoveSymbol(
     VXBaseSymbolResolverContext *ctx,
     uint64_t address);
 
+/**
+ * @brief   Clears the symbol tree.
+ * @param   ctx The exact symbol resolver context.
+ */
 void VXExactSymbolResolverContext_Clear(
     VXBaseSymbolResolverContext *ctx);
 
@@ -83,6 +124,13 @@ typedef const char* (*VXResolveSymbol_t)(
     uint64_t *offset,
     void *userData);
 
+/**
+ * @brief   Creates a custom symbol resolver.
+ * @param   resolverCb  The resolver callback consulted when symbols need to be resolved.
+ * @param   userData    A pointer to arbitrary data passed to the resolver callback.
+ *                      May also be @c NULL.
+ * @return  @c NULL if it fails, else a symbol resolver context.
+ */
 VXBaseSymbolResolverContext* VXCustomSymbolResolver_Create(
     VXResolveSymbol_t resolverCb,
     void *userData);
@@ -91,23 +139,58 @@ VXBaseSymbolResolverContext* VXCustomSymbolResolver_Create(
 
 typedef struct _VXBaseInstructionFormatterContext {int a;} VXBaseInstructionFormatterContext;
 
+/**
+ * @brief   Formats a decoded instruction.
+ * @param   ctx     The instruction formatter context.
+ * @param   info    The instruction info.
+ * @return  Pointer to the formatted instruction string. This pointer remains valid until 
+ *          this function is called again or the context is released.
+ */
 const char* VXBaseInstructionFormatter_FormatInstruction(
     VXBaseInstructionFormatterContext *ctx,
     const VXInstructionInfo *info);
 
+/**
+ * @brief   Returns a pointer to the current symbol resolver.
+ * @param   ctx     The instruction formatter context.
+ * @return  Pointer to the current symbol resolver or @c NULL if no symbol resolver is used.
+ */
 VXBaseSymbolResolverContext* VXBaseInstructionFormatter_GetSymbolResolver(
     const VXBaseInstructionFormatterContext *ctx);
 
+/**
+ * @brief   Sets a new symbol resolver.
+ * @param   ctx             The instruction formatter context.
+ * @param   symbolResolver  Pointer to a symbol resolver instance or @c NULL, if no smybol
+ *                          resolver should be used.
+ */
 void VXBaseInstructionFormatter_SetSymbolResolver(
     VXBaseInstructionFormatterContext *ctx,
     VXBaseSymbolResolverContext *resolver);
 
-void VXBaseInstructionFormatter_Release(VXBaseInstructionFormatterContext *ctx);
+/**
+ * @brief   Releases an instruction formatter.
+ * @param   ctx The context of the instruction formatter to release.
+ * The context may no longer used after it has been released.
+ */
+void VXBaseInstructionFormatter_Release(
+    VXBaseInstructionFormatterContext *ctx);
 
 /* VXIntelInstructionFormatter ================================================================ */
 
+/**
+ * @brief   Creates an Intel-syntax instruction formatter.
+ * @return  @c NULL if it fails, else an Intel instruction formatter context.
+ * @see     VXBaseInstructionFormatter_Release
+ */
 VXBaseInstructionFormatterContext* VXIntelInstructionFormatter_Create(void);
 
+/**
+ * @brief   Creates an Intel-syntax instruction formatter.
+ * @param   resolver The symbol resolver consulted to resolve symbols on formatting.
+ * @return  @c NULL if it fails, else an Intel instruction formatter context.
+ * @see     VXBaseInstructionFormatter_Release
+ */
 VXBaseInstructionFormatterContext* VXIntelInstructionFormatter_CreateEx(
     VXBaseSymbolResolverContext *resolver);