doc: Document struct typedefs

Unfortunately, Doxygen's TYPDEF_HIDES_STRUCT option is too broken.
Document struct typedefs to make autolinks work.

include/libxml/catalog.h

@@ -63,6 +63,7 @@ typedef enum {
 
 /** @endcond */
 
+/** XML catalog */
 typedef struct _xmlCatalog xmlCatalog;
 typedef xmlCatalog *xmlCatalogPtr;
 

include/libxml/dict.h

@@ -22,8 +22,8 @@
 extern "C" {
 #endif
 
-/*
- * The dictionary.
+/**
+ * Dictionary (pool for interned strings)
  */
 typedef struct _xmlDict xmlDict;
 typedef xmlDict *xmlDictPtr;

include/libxml/encoding.h

@@ -188,6 +188,7 @@ typedef xmlCharEncError
 typedef void
 (*xmlCharEncConvCtxtDtor)(void *vctxt);
 
+/** Character encoding converter */
 typedef struct _xmlCharEncodingHandler xmlCharEncodingHandler;
 typedef xmlCharEncodingHandler *xmlCharEncodingHandlerPtr;
 /**

include/libxml/hash.h

@@ -20,8 +20,10 @@
 extern "C" {
 #endif
 
-/*
- * The hash table.
+/**
+ * Hash table mapping strings to pointers
+ *
+ * Also supports lookup using two or three strings as key.
  */
 typedef struct _xmlHashTable xmlHashTable;
 typedef xmlHashTable *xmlHashTablePtr;

include/libxml/list.h

@@ -20,9 +20,19 @@
 extern "C" {
 #endif
 
+/**
+ * Linked list item
+ *
+ * @deprecated Don't use in new code.
+ */
 typedef struct _xmlLink xmlLink;
 typedef xmlLink *xmlLinkPtr;
 
+/**
+ * Linked list
+ *
+ * @deprecated Don't use in new code.
+ */
 typedef struct _xmlList xmlList;
 typedef xmlList *xmlListPtr;
 

include/libxml/parser.h

@@ -137,12 +137,6 @@ struct _xmlParserInput {
 
 /** @cond ignore */
 
-/*
- * The parser can be asked to collect Node information, i.e. at what
- * place in the file they were detected.
- *
- * NOTE: This feature is off by default and deprecated.
- */
 typedef struct _xmlParserNodeInfo xmlParserNodeInfo;
 typedef xmlParserNodeInfo *xmlParserNodeInfoPtr;
 
@@ -1181,6 +1175,11 @@ struct _xmlSAXHandler {
     xmlStructuredErrorFunc serror;
 };
 
+/**
+ * SAX handler, version 1.
+ *
+ * @deprecated Use version 2 handlers.
+ */
 typedef struct _xmlSAXHandlerV1 xmlSAXHandlerV1;
 typedef xmlSAXHandlerV1 *xmlSAXHandlerV1Ptr;
 /**

include/libxml/pattern.h

@@ -62,7 +62,7 @@ XMLPUBFUN int
 			xmlPatternMatch		(xmlPattern *comp,
 						 xmlNode *node);
 
-/* streaming interfaces */
+/** State object for streaming interface */
 typedef struct _xmlStreamCtxt xmlStreamCtxt;
 typedef xmlStreamCtxt *xmlStreamCtxtPtr;
 

include/libxml/relaxng.h

@@ -25,6 +25,7 @@
 extern "C" {
 #endif
 
+/** RelaxNG schema */
 typedef struct _xmlRelaxNG xmlRelaxNG;
 typedef xmlRelaxNG *xmlRelaxNGPtr;
 
@@ -51,12 +52,11 @@ typedef void (*xmlRelaxNGValidityWarningFunc) (void *ctx,
 							const char *msg,
 							...) LIBXML_ATTR_FORMAT(2,3);
 
-/**
- * A schemas validation context
- */
+/** RelaxNG parser context */
 typedef struct _xmlRelaxNGParserCtxt xmlRelaxNGParserCtxt;
 typedef xmlRelaxNGParserCtxt *xmlRelaxNGParserCtxtPtr;
 
+/** RelaxNG validation context */
 typedef struct _xmlRelaxNGValidCtxt xmlRelaxNGValidCtxt;
 typedef xmlRelaxNGValidCtxt *xmlRelaxNGValidCtxtPtr;
 

include/libxml/schemasInternals.h

@@ -143,15 +143,19 @@ typedef enum {
     XML_SCHEMA_CONTENT_ANY
 } xmlSchemaContentType;
 
+/** Schema value */
 typedef struct _xmlSchemaVal xmlSchemaVal;
 typedef xmlSchemaVal *xmlSchemaValPtr;
 
+/** Schema type */
 typedef struct _xmlSchemaType xmlSchemaType;
 typedef xmlSchemaType *xmlSchemaTypePtr;
 
+/** Schema facet */
 typedef struct _xmlSchemaFacet xmlSchemaFacet;
 typedef xmlSchemaFacet *xmlSchemaFacetPtr;
 
+/** Schema annotation */
 typedef struct _xmlSchemaAnnot xmlSchemaAnnot;
 typedef xmlSchemaAnnot *xmlSchemaAnnotPtr;
 /**
@@ -222,6 +226,7 @@ struct _xmlSchemaAnnot {
  */
 #define XML_SCHEMAS_ATTR_FIXED        1 << 9
 
+/** Schema attribute definition */
 typedef struct _xmlSchemaAttribute xmlSchemaAttribute;
 typedef xmlSchemaAttribute *xmlSchemaAttributePtr;
 /**
@@ -250,6 +255,7 @@ struct _xmlSchemaAttribute {
     xmlSchemaAttribute *refDecl; /* Deprecated; not used */
 };
 
+/** Linked list of schema attributes */
 typedef struct _xmlSchemaAttributeLink xmlSchemaAttributeLink;
 typedef xmlSchemaAttributeLink *xmlSchemaAttributeLinkPtr;
 /**
@@ -266,6 +272,7 @@ struct _xmlSchemaAttributeLink {
  */
 #define XML_SCHEMAS_WILDCARD_COMPLETE 1 << 0
 
+/** Namespace wildcard */
 typedef struct _xmlSchemaWildcardNs xmlSchemaWildcardNs;
 typedef xmlSchemaWildcardNs *xmlSchemaWildcardNsPtr;
 /**
@@ -276,6 +283,7 @@ struct _xmlSchemaWildcardNs {
     const xmlChar *value;/* the value */
 };
 
+/** Name wildcard */
 typedef struct _xmlSchemaWildcard xmlSchemaWildcard;
 typedef xmlSchemaWildcard *xmlSchemaWildcardPtr;
 /**
@@ -317,6 +325,7 @@ struct _xmlSchemaWildcard {
  */
 #define XML_SCHEMAS_ATTRGROUP_HAS_REFS 1 << 4
 
+/** Attribute group */
 typedef struct _xmlSchemaAttributeGroup xmlSchemaAttributeGroup;
 typedef xmlSchemaAttributeGroup *xmlSchemaAttributeGroupPtr;
 /**
@@ -344,6 +353,7 @@ struct _xmlSchemaAttributeGroup {
     void *attrUses;
 };
 
+/** Linked list of schema types */
 typedef struct _xmlSchemaTypeLink xmlSchemaTypeLink;
 typedef xmlSchemaTypeLink *xmlSchemaTypeLinkPtr;
 /**
@@ -355,6 +365,7 @@ struct _xmlSchemaTypeLink {
     xmlSchemaType *type;/* the linked type */
 };
 
+/** Linked list of schema facets */
 typedef struct _xmlSchemaFacetLink xmlSchemaFacetLink;
 typedef xmlSchemaFacetLink *xmlSchemaFacetLinkPtr;
 /**
@@ -618,6 +629,7 @@ struct _xmlSchemaType {
  */
 #define XML_SCHEMAS_ELEM_INTERNAL_CHECKED        1 << 18
 
+/** Schema element definition */
 typedef struct _xmlSchemaElement xmlSchemaElement;
 typedef xmlSchemaElement *xmlSchemaElementPtr;
 /**
@@ -689,6 +701,7 @@ struct _xmlSchemaFacet {
     xmlRegexp      *regexp; /* The regex for patterns */
 };
 
+/** Schema notation */
 typedef struct _xmlSchemaNotation xmlSchemaNotation;
 typedef xmlSchemaNotation *xmlSchemaNotationPtr;
 /**

include/libxml/schematron.h

@@ -45,9 +45,7 @@ typedef enum {
     XML_SCHEMATRON_OUT_IO = 1 << 10
 } xmlSchematronValidOptions;
 
-/**
- * The schemas related types are kept internal
- */
+/** Schematron schema */
 typedef struct _xmlSchematron xmlSchematron;
 typedef xmlSchematron *xmlSchematronPtr;
 
@@ -69,12 +67,11 @@ typedef void (*xmlSchematronValidityErrorFunc) (void *ctx, const char *msg, ...)
  */
 typedef void (*xmlSchematronValidityWarningFunc) (void *ctx, const char *msg, ...);
 
-/**
- * A schemas validation context
- */
+/** Schematron parser context */
 typedef struct _xmlSchematronParserCtxt xmlSchematronParserCtxt;
 typedef xmlSchematronParserCtxt *xmlSchematronParserCtxtPtr;
 
+/** Schematron validation context */
 typedef struct _xmlSchematronValidCtxt xmlSchematronValidCtxt;
 typedef xmlSchematronValidCtxt *xmlSchematronValidCtxtPtr;
 

include/libxml/threads.h

@@ -20,15 +20,11 @@
 extern "C" {
 #endif
 
-/*
- * xmlMutex are a simple mutual exception locks.
- */
+/** Mutual exclusion object */
 typedef struct _xmlMutex xmlMutex;
 typedef xmlMutex *xmlMutexPtr;
 
-/*
- * xmlRMutex are reentrant mutual exception locks.
- */
+/** Reentrant mutual exclusion object */
 typedef struct _xmlRMutex xmlRMutex;
 typedef xmlRMutex *xmlRMutexPtr;
 

include/libxml/tree.h

@@ -52,26 +52,38 @@ extern "C" {
  * Some of the basic types pointer to structures:
  */
 /* xmlIO.h */
+/**
+ * Parser input buffer
+ *
+ * This struct and all related functions should ultimately
+ * be removed from the public interface.
+ */
 typedef struct _xmlParserInputBuffer xmlParserInputBuffer;
 typedef xmlParserInputBuffer *xmlParserInputBufferPtr;
 
+/** Output buffer */
 typedef struct _xmlOutputBuffer xmlOutputBuffer;
 typedef xmlOutputBuffer *xmlOutputBufferPtr;
 
 /* parser.h */
+/** Parser input */
 typedef struct _xmlParserInput xmlParserInput;
 typedef xmlParserInput *xmlParserInputPtr;
 
+/** Parser context */
 typedef struct _xmlParserCtxt xmlParserCtxt;
 typedef xmlParserCtxt *xmlParserCtxtPtr;
 
+/** SAX locator */
 typedef struct _xmlSAXLocator xmlSAXLocator;
 typedef xmlSAXLocator *xmlSAXLocatorPtr;
 
+/** SAX handler */
 typedef struct _xmlSAXHandler xmlSAXHandler;
 typedef xmlSAXHandler *xmlSAXHandlerPtr;
 
 /* entities.h */
+/** Entity declaration */
 typedef struct _xmlEntity xmlEntity;
 typedef xmlEntity *xmlEntityPtr;
 
@@ -87,6 +99,7 @@ typedef enum {
     XML_BUFFER_ALLOC_BOUNDED	/* limit the upper size of the buffer */
 } xmlBufferAllocationScheme;
 
+/** Buffer type */
 typedef struct _xmlBuffer xmlBuffer;
 typedef xmlBuffer *xmlBufferPtr;
 /**
@@ -106,9 +119,7 @@ struct _xmlBuffer {
     xmlChar *contentIO XML_DEPRECATED_MEMBER;
 };
 
-/**
- * A buffer structure, new one, the actual structure internals are not public
- */
+/** Buffer with 64-bit support */
 typedef struct _xmlBuf xmlBuf;
 typedef xmlBuf *xmlBufPtr;
 
@@ -266,6 +277,7 @@ typedef enum {
 #define XML_DOCB_DOCUMENT_NODE 21
 /** @endcond */
 
+/** Notation declaration */
 typedef struct _xmlNotation xmlNotation;
 typedef xmlNotation *xmlNotationPtr;
 /**
@@ -309,6 +321,7 @@ typedef enum {
     XML_ATTRIBUTE_FIXED
 } xmlAttributeDefault;
 
+/** Enumeration in a DTD */
 typedef struct _xmlEnumeration xmlEnumeration;
 typedef xmlEnumeration *xmlEnumerationPtr;
 /**
@@ -324,6 +337,7 @@ struct _xmlEnumeration {
     const xmlChar            *name XML_DEPRECATED_MEMBER;
 };
 
+/** Attribute declaration */
 typedef struct _xmlAttribute xmlAttribute;
 typedef xmlAttribute *xmlAttributePtr;
 /**
@@ -388,6 +402,7 @@ typedef enum {
     XML_ELEMENT_CONTENT_PLUS
 } xmlElementContentOccur;
 
+/** Element content in element declarations */
 typedef struct _xmlElementContent xmlElementContent;
 typedef xmlElementContent *xmlElementContentPtr;
 /**
@@ -425,6 +440,7 @@ typedef enum {
     XML_ELEMENT_TYPE_ELEMENT
 } xmlElementTypeVal;
 
+/** Element declaration */
 typedef struct _xmlElement xmlElement;
 typedef xmlElement *xmlElementPtr;
 /**
@@ -476,6 +492,7 @@ struct _xmlElement {
 #define XML_LOCAL_NAMESPACE XML_NAMESPACE_DECL
 typedef xmlElementType xmlNsType;
 
+/** Namespace declaration */
 typedef struct _xmlNs xmlNs;
 typedef xmlNs *xmlNsPtr;
 /**
@@ -506,6 +523,7 @@ struct _xmlNs {
     struct _xmlDoc *context XML_DEPRECATED_MEMBER;
 };
 
+/** Document type definition (DTD) */
 typedef struct _xmlDtd xmlDtd;
 typedef xmlDtd *xmlDtdPtr;
 /**
@@ -553,6 +571,7 @@ struct _xmlDtd {
     void          *pentities XML_DEPRECATED_MEMBER;
 };
 
+/** Attribute of an element */
 typedef struct _xmlAttr xmlAttr;
 typedef xmlAttr *xmlAttrPtr;
 /**
@@ -587,6 +606,7 @@ struct _xmlAttr {
     struct _xmlID   *id XML_DEPRECATED_MEMBER;
 };
 
+/** Extra data for ID attributes */
 typedef struct _xmlID xmlID;
 typedef xmlID *xmlIDPtr;
 /**
@@ -630,6 +650,7 @@ struct _xmlRef {
 };
 /** @endcond */
 
+/** Generic node type in an XML or HTML tree */
 typedef struct _xmlNode xmlNode;
 typedef xmlNode *xmlNodePtr;
 /**
@@ -749,6 +770,7 @@ typedef enum {
     XML_DOC_HTML		= 1<<7
 } xmlDocProperties;
 
+/** XML or HTML document */
 typedef struct _xmlDoc xmlDoc;
 typedef xmlDoc *xmlDocPtr;
 /**
@@ -817,6 +839,7 @@ struct _xmlDoc {
 };
 
 
+/** Context for DOM wrapper operations */
 typedef struct _xmlDOMWrapCtxt xmlDOMWrapCtxt;
 typedef xmlDOMWrapCtxt *xmlDOMWrapCtxtPtr;
 

include/libxml/uri.h

@@ -22,6 +22,7 @@
 extern "C" {
 #endif
 
+/** Parsed URI */
 typedef struct _xmlURI xmlURI;
 typedef xmlURI *xmlURIPtr;
 /**

include/libxml/xinclude.h

@@ -65,6 +65,7 @@ extern "C" {
  */
 #define XINCLUDE_PARSE_XPOINTER (const xmlChar *) "xpointer"
 
+/** XInclude context */
 typedef struct _xmlXIncludeCtxt xmlXIncludeCtxt;
 typedef xmlXIncludeCtxt *xmlXIncludeCtxtPtr;
 

include/libxml/xmlautomata.h

@@ -24,13 +24,15 @@ extern "C" {
 #endif
 
 /**
- * A libxml automata description, It can be compiled into a regexp
+ * A libxml automata description
+ *
+ * It can be compiled into a regexp
  */
 typedef struct _xmlAutomata xmlAutomata;
 typedef xmlAutomata *xmlAutomataPtr;
 
 /**
- * A state int the automata description,
+ * A state in the automata description
  */
 typedef struct _xmlAutomataState xmlAutomataState;
 typedef xmlAutomataState *xmlAutomataStatePtr;

include/libxml/xmlerror.h

@@ -110,6 +110,7 @@ typedef enum {
     XML_FROM_URI
 } xmlErrorDomain;
 
+/** Structured error */
 typedef struct _xmlError xmlError;
 typedef xmlError *xmlErrorPtr;
 /**

include/libxml/xmlreader.h

@@ -112,14 +112,8 @@ typedef enum {
     XML_READER_TYPE_XML_DECLARATION = 17
 } xmlReaderTypes;
 
-/**
- * Structure for an xmlReader context.
- */
+/** xmlReader context */
 typedef struct _xmlTextReader xmlTextReader;
-
-/**
- * Pointer to an xmlReader context.
- */
 typedef xmlTextReader *xmlTextReaderPtr;
 
 /*

include/libxml/xmlsave.h

@@ -86,6 +86,7 @@ typedef enum {
     XML_SAVE_INDENT     = 1<<10
 } xmlSaveOption;
 
+/** XML and HTML serializer */
 typedef struct _xmlSaveCtxt xmlSaveCtxt;
 typedef xmlSaveCtxt *xmlSaveCtxtPtr;
 

include/libxml/xmlschemas.h

@@ -83,9 +83,7 @@ typedef enum {
 	* xsi:noNamespaceSchemaLocation
 */
 
-/**
- * The schemas related types are kept internal
- */
+/** XML schema */
 typedef struct _xmlSchema xmlSchema;
 typedef xmlSchema *xmlSchemaPtr;
 
@@ -109,12 +107,11 @@ typedef void (*xmlSchemaValidityErrorFunc)
 typedef void (*xmlSchemaValidityWarningFunc)
                  (void *ctx, const char *msg, ...) LIBXML_ATTR_FORMAT(2,3);
 
-/**
- * A schemas validation context
- */
+/** Schema parser context */
 typedef struct _xmlSchemaParserCtxt xmlSchemaParserCtxt;
 typedef xmlSchemaParserCtxt *xmlSchemaParserCtxtPtr;
 
+/** Schema validation context */
 typedef struct _xmlSchemaValidCtxt xmlSchemaValidCtxt;
 typedef xmlSchemaValidCtxt *xmlSchemaValidCtxtPtr;
 
@@ -224,7 +221,7 @@ XMLPUBFUN int
 XMLPUBFUN xmlParserCtxt *
 	    xmlSchemaValidCtxtGetParserCtxt(xmlSchemaValidCtxt *ctxt);
 
-/*
+/**
  * Interface to insert Schemas SAX validation in a SAX stream
  */
 typedef struct _xmlSchemaSAXPlug xmlSchemaSAXPlugStruct;

include/libxml/xmlwriter.h

@@ -26,6 +26,7 @@
 extern "C" {
 #endif
 
+    /** Writer object */
     typedef struct _xmlTextWriter xmlTextWriter;
     typedef xmlTextWriter *xmlTextWriterPtr;
 

include/libxml/xpath.h

@@ -34,8 +34,10 @@
 extern "C" {
 #endif
 
+/** XPath context */
 typedef struct _xmlXPathContext xmlXPathContext;
 typedef xmlXPathContext *xmlXPathContextPtr;
+/** XPath parser and evaluation context */
 typedef struct _xmlXPathParserContext xmlXPathParserContext;
 typedef xmlXPathParserContext *xmlXPathParserContextPtr;
 
@@ -73,6 +75,7 @@ typedef enum {
     XPATH_RECURSION_LIMIT_EXCEEDED
 } xmlXPathError;
 
+/** XPath node set */
 typedef struct _xmlNodeSet xmlNodeSet;
 typedef xmlNodeSet *xmlNodeSetPtr;
 /**
@@ -112,6 +115,7 @@ typedef enum {
 #define XPATH_LOCATIONSET 7
 /** @endcond */
 
+/** XPath object */
 typedef struct _xmlXPathObject xmlXPathObject;
 typedef xmlXPathObject *xmlXPathObjectPtr;
 /**
@@ -352,16 +356,15 @@ struct _xmlXPathContext {
     int depth;
 };
 
-/*
- * The structure of a compiled expression form is not public.
- */
-
+/** Compiled XPath expression */
 typedef struct _xmlXPathCompExpr xmlXPathCompExpr;
 typedef xmlXPathCompExpr *xmlXPathCompExprPtr;
 
 /**
  * An XPath parser context. It contains pure parsing information,
  * an xmlXPathContext, and the stack of objects.
+ *
+ * This struct is used for evaluation as well and misnamed.
  */
 struct _xmlXPathParserContext {
     /* the current char being parsed */