@@ -14,32 +14,90 @@
 
 extern int _OFXMLParser_reference;
 
 @class OFXMLParser;
 
+/**
+ * A protocol that needs to be implemented by delegates for OFXMLParser.
+ */
 @protocol OFXMLParserDelegate
+/**
+ * This callback is called when the XML parser found the start of a new tag.
+ *
+ * \param name The name of the tag which just started
+ * \param prefix The prefix of the tag which just started or nil
+ * \param ns The namespace of the tag which just started or nil
+ * \param attrs The attributes included in the tag which just started or nil
+ */
 -     (void)xmlParser: (OFXMLParser*)parser
   didStartTagWithName: (OFString*)name
 	       prefix: (OFString*)prefix
 	    namespace: (OFString*)ns
 	   attributes: (OFArray*)attrs;
+
+/**
+ * This callback is called when the XML parser found the end of a tag.
+ *
+ * \param name The name of the tag which just ended
+ * \param prefix The prefix of the tag which just ended or nil
+ * \param ns The namespace of the tag which just ended or nil
+ */
 -   (void)xmlParser: (OFXMLParser*)parser
   didEndTagWithName: (OFString*)name
 	     prefix: (OFString*)prefix
 	  namespace: (OFString*)ns;
+
+/**
+ * This callback is called when the XML parser found a string.
+ *
+ * \param string The string the XML parser found
+ */
 - (void)xmlParser: (OFXMLParser*)parser
       foundString: (OFString*)string;
+
+/**
+ * This callback is called when the XML parser found a comment.
+ *
+ * \param comment The comment the XML parser found
+ */
 - (void)xmlParser: (OFXMLParser*)parser
      foundComment: (OFString*)comment;
+
+/**
+ * This callback is called when the XML parser found an entity it doesn't know.
+ * The callback is supposed to return a substitution for the entity or nil if
+ * it is not known to the callback as well, in which case an exception will be
+ * risen.
+ *
+ * \param entity The name of the entity the XML parser didn't know
+ * \return A substitution for the entity or nil
+ */
 -    (OFString*)xmlParser: (OFXMLParser*)parser
   foundUnknownEntityNamed: (OFString*)entity;
 @end
 
+/**
+ * A protocol that needs to be implemented by delegates for 
+ * stringByXMLUnescapingWithHandler:.
+ */
 @protocol OFXMLUnescapingDelegate
+/**
+ * This callback is called when an unknown entity was found while trying to
+ * unescape XML. The callback is supposed to return a substitution for the
+ * entity or nil if it is not known to the callback as well, in which case an
+ * exception will be risen.
+ *
+ * \param entity The name of the entity that is unknown
+ * \return A substitution for the entity or nil
+ */
 - (OFString*)foundUnknownEntityNamed: (OFString*)entitiy;
 @end
 
+/**
+ * An event-based XML parser which calls the delegate's callbacks as soon as
+ * it finds something, thus suitable for streams as well.
+ */
 @interface OFXMLParser: OFObject <OFXMLUnescapingDelegate>
 {
 	OFObject <OFXMLParserDelegate> *delegate;
 	enum {
 		OF_XMLPARSER_OUTSIDE_TAG,
@@ -66,13 +124,33 @@
 	OFString *attr_prefix;
 	char delim;
 	OFArray *previous;
 }
 
+/**
+ * \return A new, autoreleased OFXMLParser
+ */
 + xmlParser;
+
+/**
+ * \return The delegate that is used by the XML parser
+ */
 - (id)delegate;
+
+/**
+ * Sets the delegate the OFXMLParser should use.
+ *
+ * \param delegate The delegate to use
+ */
 - setDelegate: (OFObject <OFXMLParserDelegate>*)delegate;
+
+/**
+ * Parses a buffer with the specified size.
+ *
+ * \param buf The buffer to parse
+ * \param size The size of the buffer
+ */
 - parseBuffer: (const char*)buf
      withSize: (size_t)size;
 @end
 
 /**