[poppler] poppler/qt4/src: Doxyfile, 1.3, 1.4 poppler-qt4.h, 1.17, 1.18

[Brad Hards]

Update of /cvs/poppler/poppler/qt4/src
In directory gabe:/tmp/cvs-serv8011/qt4/src

Modified Files:
	Doxyfile poppler-qt4.h 
Log Message:
* qt4/src/Doxyfile (JAVADOC_AUTOBRIEF): Turned on automatic
\brief mode.

* qt4/src/poppler-qt4.h: Update API documentation. Patch from
Stefan Kebekus, with some changes. Removed \brief entries.



Index: Doxyfile
===================================================================
RCS file: /cvs/poppler/poppler/qt4/src/Doxyfile,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- Doxyfile	3 Dec 2005 21:35:46 -0000	1.3
+++ Doxyfile	27 Dec 2005 05:08:34 -0000	1.4
@@ -138,7 +138,7 @@
 # comments will behave just like the Qt-style comments (thus requiring an 
 # explicit @brief command for a brief description.
 
-JAVADOC_AUTOBRIEF      = NO
+JAVADOC_AUTOBRIEF      = YES
 
 # The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen 
 # treat a multi-line C++ special comment block (i.e. a block of //! or /// 

Index: poppler-qt4.h
===================================================================
RCS file: /cvs/poppler/poppler/qt4/src/poppler-qt4.h,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -d -r1.17 -r1.18
--- poppler-qt4.h	10 Dec 2005 10:52:16 -0000	1.17
+++ poppler-qt4.h	27 Dec 2005 05:08:34 -0000	1.18
@@ -36,13 +36,36 @@
     class PageData;
 
     class TextBoxData;
+
+    /**
+        describes the physical location of text on a document page
+       
+        This very simple class describes the physical location of text
+	on the page. It consists of
+	- a QString that contains the text
+	- a QRectF that gives a box that describes where on the page
+	the text is found.
+    */
     class TextBox {
     public:
+      /**
+	 The default constructor sets the text and the rectangle the
+	 contains the text. Coordinated for the bBox are in points =
+	 1/72 of an inch.
+      */
       TextBox(const QString& text, const QRectF &bBox);
-      
+
+      /**
+	  returns the text
+      */      
       const QString &text() const;
+
+      /**
+	  returns the position of the text, in point, i.e., 1/72 of
+	 an inch
+      */
       const QRectF &boundingBox() const;
-	
+
     private:
 	TextBoxData *m_data;
     };
@@ -129,7 +152,7 @@
 	~Page();
 
 	/**
-	   Render the page to a QPixmap using the Splash renderer
+	    Render the page to a QPixmap using the Splash renderer
 	 
 	   This method can be used to render the page to a QPixmap. It
 	   uses the "Splash" rendering engine that is included in the
@@ -160,36 +183,42 @@
            returned then has size (w, h), independent of the page
            size.
 
-	   @param x specifies the left x-coordinate of the box, in
+	   \param x specifies the left x-coordinate of the box, in
 	   pixels.
 
-	   @param y specifies the top y-coordinate of the box, in
+	   \param y specifies the top y-coordinate of the box, in
 	   pixels.
 
-	   @param w specifies the width of the box, in pixels.
+	   \param w specifies the width of the box, in pixels.
 
-	   @param h specifies the height of the box, in pixels.
+	   \param h specifies the height of the box, in pixels.
 
-	   @param xres horizontal resolution of the graphics device,
+	   \param xres horizontal resolution of the graphics device,
 	   in dots per inch
 
-	   @param yres vertical resolution of the graphics device, in
+	   \param yres vertical resolution of the graphics device, in
 	   dots per inch
 
-	   @warning The parameter (x,y,w,h) are not
-	   well-tested. Unusual or meaningless paramerts may lead to
-	   rather unexpexted results.
+	   \warning The parameter (x,y,w,h) are not
+	   well-tested. Unusual or meaningless parameters may lead to
+	   rather unexpected results.
 
-	   @returns pointer to a QPixmap, or NULL on failure. The
+	   \returns pointer to a QPixmap, or NULL on failure. The
 	   pixmap returned must be deleted.
 	 */
 	QPixmap *splashRenderToPixmap(double xres=72.0, double yres=72.0, int x=-1, int y=-1, int w=-1, int h=-1) const;
 	
 	/**
-	   Render the page to a pixmap using the Arthur (Qt4) renderer
+	    Render the page to a pixmap using the Arthur (Qt4) renderer
 	   
 	   \param q pointer to a QPixmap that is already set to the
 	   intended size.
+
+	   \param xres horizontal resolution of the graphics device,
+	   in dots per inch
+
+	   \param yres vertical resolution of the graphics device, in
+	   dots per inch
 	   
 	   You are meant to create the pixmap before passing it to
 	   this routine, using something like:
@@ -197,26 +226,44 @@
 	   QPixmap* myPixmap = new QPixmap(page->pageSize());
 	   page->renderToPixmap(myPixmap);
 	   \endcode
+
+	   \warning This is a work in progress. Results are unlikely to be of
+	   high quality. 
 	*/
         void renderToPixmap(QPixmap *q, double xres=72.0, double yres=72.0) const;
 
 	/**
 	   Returns the text that is inside a specified rectangle
 
-	   \param rect the rectangle specifying the area of interest
+	   \param rect the rectangle specifying the area of interest,
+	   with coordinates given in points, i.e., 1/72th of an inch.
 	   If rect is null, all text on the page is given
 	**/
 	QString text(const QRectF &rect) const;
 
+	/**
+	   Returns a list of text of the page
+
+	   This method returns a QList of TextBoxes that contain all
+	   the text of the page, with roughly one text word of text
+	   per TextBox item.
+	   
+	   For text written in western languages (left-to-right and
+	   up-to-down), the QList contains the text in the proper
+	   order.
+
+	   \warning This method is not tested with Asian scripts
+	*/
+
 	QList<TextBox*> textList() const;
 
 	/**
-	   The dimensions of the page, in points.
+	   \return The dimensions of the page, in points (i.e. 1/72th on an inch)
 	*/
 	QSizeF pageSizeF() const;
 
 	/**
-	   The dimensions of the page, in points.
+	   The dimensions of the page, in pixels.
 	*/
 	QSize pageSize() const;