Attachment 66366 Details for Bug 54279 – A patch for some added doxygen documentation

[patch] A patch for some added doxygen documentation

added_doxygen_comments.patch (text/plain), 41.01 KB, created by cheshirekow on 2012-08-30 18:50:17 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: cheshirekow

Created: 2012-08-30 18:50:17 UTC

Size: 41.01 KB

patch

obsolete

>From 9d480eefad9a4ee8f243f473dc369097340904bb Mon Sep 17 00:00:00 2001
>From: Josh Bialkowski <jbialk@mit.edu>
>Date: Tue, 10 Jul 2012 16:25:23 -0400
>Subject: [PATCH 1/2] Adding some doxygen comments to the API
>
>---
> poppler/Annot.h         |    2 +
> poppler/Link.h          |   32 +++---
> poppler/Object.h        |   26 ++++-
> poppler/OutputDev.h     |   53 +++++-----
> poppler/PDFDoc.h        |  224 ++++++++++++++++++++++++++++++++++--------
> poppler/PDFDocBuilder.h |    2 +
> poppler/Page.h          |  248 +++++++++++++++++++++++++++++++++++++++++------
> poppler/XRef.h          |   50 ++++++---
> 8 files changed, 502 insertions(+), 135 deletions(-)
>
>diff --git a/poppler/Annot.h b/poppler/Annot.h
>index 0d20cc7..1a5157b 100644
>--- a/poppler/Annot.h
>+++ b/poppler/Annot.h
>@@ -471,6 +471,8 @@ private:
> // Annot
> //------------------------------------------------------------------------
> 
>+/// An object of this class stores a single annotation to a page in a PDF
>+/// document
> class Annot {
>   friend class Annots;
>   friend class Page;
>diff --git a/poppler/Link.h b/poppler/Link.h
>index 8e2df24..64476ed 100644
>--- a/poppler/Link.h
>+++ b/poppler/Link.h
>@@ -44,36 +44,37 @@ class Annots;
> // LinkAction
> //------------------------------------------------------------------------
> 
>+/// Enumerates the types of a PDF hyper-reference (link)
> enum LinkActionKind {
>-  actionGoTo,			// go to destination
>-  actionGoToR,			// go to destination in new file
>-  actionLaunch,			// launch app (or open document)
>-  actionURI,			// URI
>-  actionNamed,			// named action
>-  actionMovie,			// movie action
>+  actionGoTo,			///< go to destination
>+  actionGoToR,			///< go to destination in new file
>+  actionLaunch,			///< launch app (or open document)
>+  actionURI,			///< URI
>+  actionNamed,			///< named action
>+  actionMovie,			///< movie action
>   actionRendition,
>-  actionSound,			// sound action
>-  actionJavaScript,		// JavaScript action
>-  actionOCGState,               // Set-OCG-State action
>-  actionUnknown			// anything else
>+  actionSound,			///< sound action
>+  actionJavaScript,		///< JavaScript action
>+  actionOCGState,       ///< Set-OCG-State action
>+  actionUnknown			///< anything else
> };
> 
> class LinkAction {
> public:
> 
>-  // Destructor.
>+  /// Destructor.
>   virtual ~LinkAction() {}
> 
>-  // Was the LinkAction created successfully?
>+  /// Was the LinkAction created successfully?
>   virtual GBool isOk() = 0;
> 
>-  // Check link action type.
>+  /// Check link action type.
>   virtual LinkActionKind getKind() = 0;
> 
>-  // Parse a destination (old-style action) name, string, or array.
>+  /// Parse a destination (old-style action) name, string, or array.
>   static LinkAction *parseDest(Object *obj);
> 
>-  // Parse an action dictionary.
>+  /// Parse an action dictionary.
>   static LinkAction *parseAction(Object *obj, GooString *baseURI = NULL);
> };
> 
>@@ -461,6 +462,7 @@ private:
> // Links
> //------------------------------------------------------------------------
> 
>+/// An object of this class stores a list of links (hyper-references)
> class Links {
> public:
> 
>diff --git a/poppler/Object.h b/poppler/Object.h
>index c885d73..618f61f 100644
>--- a/poppler/Object.h
>+++ b/poppler/Object.h
>@@ -109,6 +109,23 @@ enum ObjType {
> #define initObj(t) zeroUnion(); type = t
> #endif
> 
>+
>+/// A union type, similar to boost::variant
>+/**
>+ *  An Object may be any one of the following
>+ *  * a boolean
>+ *  * an integer
>+ *  * a real number
>+ *  * a string
>+ *  * a name (???)
>+ *  * nothing / empty
>+ *  * an array of Object*
>+ *  * a dictionary (map of const char* -> Object*)
>+ *  * a reference to an object
>+ *  * a file stream
>+ *  * an error
>+ *  * an unsigned integer
>+ */
> class Object {
> public:
>   // clear the anonymous union as best we can -- clear at least a pointer
>@@ -153,15 +170,16 @@ public:
>     return obj;
>   }
> 
>-  // If object is a Ref, fetch and return the referenced object.
>-  // Otherwise, return a copy of the object.
>+  /// If object is a Ref, fetch and return the referenced object.
>+  /// Otherwise, return a copy of the object.
>   Object *fetch(XRef *xref, Object *obj, int recursion = 0);
> 
>-  // Free object contents.
>+  /// Free object contents.
>   void free();
> 
>-  // Type checking.
>+  /// Type checking.
>   ObjType getType() { return type; }
>+
>   GBool isBool() { return type == objBool; }
>   GBool isInt() { return type == objInt; }
>   GBool isReal() { return type == objReal; }
>diff --git a/poppler/OutputDev.h b/poppler/OutputDev.h
>index 15af90a..a920962 100644
>--- a/poppler/OutputDev.h
>+++ b/poppler/OutputDev.h
>@@ -20,7 +20,7 @@
> // Copyright (C) 2009-2012 Thomas Freitag <Thomas.Freitag@alfa.de>
> // Copyright (C) 2009, 2011 Carlos Garcia Campos <carlosgc@gnome.org>
> // Copyright (C) 2009, 2012 Albert Astals Cid <aacid@kde.org>
>-// Copyright (C) 2010 Christian Feuersänger <cfeuersaenger@googlemail.com>
>+// Copyright (C) 2010 Christian Feuersï¿½nger <cfeuersaenger@googlemail.com>
> // Copyright (C) 2012 Fabio D'Urso <fabiodurso@hotmail.it>
> //
> // To see a description of the changes please see the Changelog file that
>@@ -67,6 +67,7 @@ class Function;
> // OutputDev
> //------------------------------------------------------------------------
> 
>+/// Interface for rendering backends
> class OutputDev {
> public:
> 
>@@ -78,49 +79,49 @@ public:
> 
>   //----- get info about output device
> 
>-  // Does this device use upside-down coordinates?
>-  // (Upside-down means (0,0) is the top left corner of the page.)
>+  /// Does this device use upside-down coordinates?
>+  /// (Upside-down means (0,0) is the top left corner of the page.)
>   virtual GBool upsideDown() = 0;
> 
>-  // Does this device use drawChar() or drawString()?
>+  /// Does this device use drawChar() or drawString()?
>   virtual GBool useDrawChar() = 0;
> 
>-  // Does this device use tilingPatternFill()?  If this returns false,
>-  // tiling pattern fills will be reduced to a series of other drawing
>-  // operations.
>+  /// Does this device use tilingPatternFill()?  If this returns false,
>+  /// tiling pattern fills will be reduced to a series of other drawing
>+  /// operations.
>   virtual GBool useTilingPatternFill() { return gFalse; }
> 
>-  // Does this device support specific shading types?
>-  // see gouraudTriangleShadedFill() and patchMeshShadedFill()
>+  /// Does this device support specific shading types?
>+  /// see gouraudTriangleShadedFill() and patchMeshShadedFill()
>   virtual GBool useShadedFills(int type) { return gFalse; }
> 
>-  // Does this device use FillColorStop()?
>+  /// Does this device use FillColorStop()?
>   virtual GBool useFillColorStop() { return gFalse; }
> 
>-  // Does this device use drawForm()?  If this returns false,
>-  // form-type XObjects will be interpreted (i.e., unrolled).
>+  /// Does this device use drawForm()?  If this returns false,
>+  /// form-type XObjects will be interpreted (i.e., unrolled).
>   virtual GBool useDrawForm() { return gFalse; }
> 
>-  // Does this device use beginType3Char/endType3Char?  Otherwise,
>-  // text in Type 3 fonts will be drawn with drawChar/drawString.
>+  /// Does this device use beginType3Char/endType3Char?  Otherwise,
>+  /// text in Type 3 fonts will be drawn with drawChar/drawString.
>   virtual GBool interpretType3Chars() = 0;
> 
>-  // Does this device need non-text content?
>+  /// Does this device need non-text content?
>   virtual GBool needNonText() { return gTrue; }
> 
>-  // Does this device require incCharCount to be called for text on
>-  // non-shown layers?
>+  /// Does this device require incCharCount to be called for text on
>+  /// non-shown layers?
>   virtual GBool needCharCount() { return gFalse; }
> 
>   //----- initialization and control
> 
>-  // Set default transform matrix.
>+  /// Set default transform matrix.
>   virtual void setDefaultCTM(double *ctm);
> 
>-  // Check to see if a page slice should be displayed.  If this
>-  // returns false, the page display is aborted.  Typically, an
>-  // OutputDev will use some alternate means to display the page
>-  // before returning false.
>+  /// Check to see if a page slice should be displayed.  If this
>+  /// returns false, the page display is aborted.  Typically, an
>+  /// OutputDev will use some alternate means to display the page
>+  /// before returning false.
>   virtual GBool checkPageSlice(Page *page, double hDPI, double vDPI,
> 			       int rotate, GBool useMediaBox, GBool crop,
> 			       int sliceX, int sliceY, int sliceW, int sliceH,
>@@ -131,18 +132,18 @@ public:
> 			       void *annotDisplayDecideCbkData = NULL)
>     { return gTrue; }
> 
>-  // Start a page.
>+  /// Start a page.
>   virtual void startPage(int pageNum, GfxState *state) {}
> 
>-  // End a page.
>+  /// End a page.
>   virtual void endPage() {}
> 
>-  // Dump page contents to display.
>+  /// Dump page contents to display.
>   virtual void dump() {}
> 
>   //----- coordinate conversion
> 
>-  // Convert between device and user coordinates.
>+  /// Convert between device and user coordinates.
>   virtual void cvtDevToUser(double dx, double dy, double *ux, double *uy);
>   virtual void cvtUserToDev(double ux, double uy, int *dx, int *dy);
> 
>diff --git a/poppler/PDFDoc.h b/poppler/PDFDoc.h
>index 468f698..e0f9de4 100644
>--- a/poppler/PDFDoc.h
>+++ b/poppler/PDFDoc.h
>@@ -65,9 +65,18 @@ enum PDFWriteMode {
> // PDFDoc
> //------------------------------------------------------------------------
> 
>+/// Appears to be the main class for a pdf document. An object of this class
>+/// represents a PDF document which is loaded into memory
> class PDFDoc {
> public:
> 
>+  /// construct a pdf document by loading a pdf from the file system
>+  /**
>+   *  @param fileNameA       the path to the document
>+   *  @param ownerPassword
>+   *  @param userPassword
>+   *  @param guiDataA
>+   */
>   PDFDoc(GooString *fileNameA, GooString *ownerPassword = NULL,
> 	 GooString *userPassword = NULL, void *guiDataA = NULL);
> 
>@@ -76,69 +85,111 @@ public:
> 	 GooString *userPassword = NULL, void *guiDataA = NULL);
> #endif
> 
>+  /// construct a pdf document by reading in data from a stream
>+  /**
>+   *  @param strA            the stream to read
>+   *  @param ownerPassword
>+   *  @param userPassword
>+   *  @param guiDataA
>+   */
>   PDFDoc(BaseStream *strA, GooString *ownerPassword = NULL,
> 	 GooString *userPassword = NULL, void *guiDataA = NULL);
>+
>   ~PDFDoc();
> 
>   static PDFDoc *ErrorPDFDoc(int errorCode, GooString *fileNameA = NULL);
> 
>-  // Was PDF document successfully opened?
>+  /// Was PDF document successfully opened?
>   GBool isOk() { return ok; }
> 
>-  // Get the error code (if isOk() returns false).
>+  /// Get the error code (if isOk() returns false).
>   int getErrorCode() { return errCode; }
> 
>-  // Get the error code returned by fopen() (if getErrorCode() == 
>-  // errOpenFile).
>+  /// Get the error code returned by fopen() (if getErrorCode() ==
>+  /// errOpenFile).
>   int getFopenErrno() { return fopenErrno; }
> 
>-  // Get file name.
>+  /// Return the filename of the file that was opened to instantiate this
>+  /// pdf document
>   GooString *getFileName() { return fileName; }
> #ifdef _WIN32
>   wchar_t *getFileNameU() { return fileNameU; }
> #endif
> 
>-  // Get the linearization table.
>+  /// Get the linearization table.
>   Linearization *getLinearization();
> 
>-  // Get the xref table.
>+  /// Get the xref table.
>   XRef *getXRef() { return xref; }
> 
>-  // Get catalog.
>+  /// Get catalog.
>   Catalog *getCatalog() { return catalog; }
> 
>-  // Get optional content configuration
>+  /// Get optional content configuration
>   OCGs *getOptContentConfig() { return catalog->getOptContentConfig(); }
> 
>-  // Get base stream.
>+  /// Get base stream, the stream from which this PDF document was read
>   BaseStream *getBaseStream() { return str; }
> 
>   // Get page parameters.
>+
>+  /// get the width of a page in the document
>   double getPageMediaWidth(int page)
>     { return getPage(page) ? getPage(page)->getMediaWidth() : 0.0 ; }
>+
>+  /// get the height of the page in the document
>+  /**
>+   *    \todo Doc: What are the units?
>+   */
>   double getPageMediaHeight(int page)
>     { return getPage(page) ? getPage(page)->getMediaHeight() : 0.0 ; }
>+
>+  /// get the width of the page after whatever cropping is defined for it
>+  /**
>+   *    \todo Doc: the documentation for this is a guess
>+   */
>   double getPageCropWidth(int page)
>     { return getPage(page) ? getPage(page)->getCropWidth() : 0.0 ; }
>+
>+  /// get the height of the page after whatever cropping is defined for it
>+  /**
>+   *    \todo Doc: the documentation for this is a guess
>+   */
>   double getPageCropHeight(int page)
>     { return getPage(page) ? getPage(page)->getCropHeight() : 0.0 ; }
>+
>+  /// get the rotation of a page in the document
>   int getPageRotate(int page)
>     { return getPage(page) ? getPage(page)->getRotate() : 0 ; }
> 
>-  // Get number of pages.
>+  /// Get the number of pages in the document
>   int getNumPages();
> 
>-  // Return the contents of the metadata stream, or NULL if there is
>-  // no metadata.
>+  /// Return the contents of the metadata stream, or NULL if there is
>+  /// no metadata.
>   GooString *readMetadata() { return catalog->readMetadata(); }
> 
>-  // Return the structure tree root object.
>+  /// Return the structure tree root object.
>   Object *getStructTreeRoot() { return catalog->getStructTreeRoot(); }
> 
>-  // Get page.
>+  /// Return data for the specified page
>   Page *getPage(int page);
> 
>-  // Display a page.
>+  /// Render a page.
>+  /**
>+   *  @param out            pointer to output device to render to
>+   *  @param page           the page to render
>+   *  @param hDPI           horizontal resolution in dots per inch
>+   *  @param vDPI           vertical resolution in dots per inch
>+   *  @param rotate
>+   *  @param useMediaBox
>+   *  @param crop
>+   *  @param printing
>+   *  @param abortCheckCbk
>+   *  @param abortCheckCbkData
>+   *  @param annotDisplayDecideCbk
>+   *  @param annotDisplayDecideCbkData
>+   */
>   void displayPage(OutputDev *out, int page,
> 		   double hDPI, double vDPI, int rotate,
> 		   GBool useMediaBox, GBool crop, GBool printing,
>@@ -147,7 +198,22 @@ public:
>                    GBool (*annotDisplayDecideCbk)(Annot *annot, void *user_data) = NULL,
>                    void *annotDisplayDecideCbkData = NULL);
> 
>-  // Display a range of pages.
>+  /// Render a range of pages.
>+  /**
>+   *  @param out
>+   *  @param firstPage
>+   *  @param lastPage
>+   *  @param hDPI
>+   *  @param vDPI
>+   *  @param rotate
>+   *  @param useMediaBox
>+   *  @param crop
>+   *  @param printing
>+   *  @param abortCheckCbk
>+   *  @param abortCheckCbkData
>+   *  @param annotDisplayDecideCbk
>+   *  @param annotDisplayDecideCbkData
>+   */
>   void displayPages(OutputDev *out, int firstPage, int lastPage,
> 		    double hDPI, double vDPI, int rotate,
> 		    GBool useMediaBox, GBool crop, GBool printing,
>@@ -156,7 +222,25 @@ public:
>                     GBool (*annotDisplayDecideCbk)(Annot *annot, void *user_data) = NULL,
>                     void *annotDisplayDecideCbkData = NULL);
> 
>-  // Display part of a page.
>+  /// Render a rectangular subregion of a page.
>+  /**
>+   *  @param out
>+   *  @param page
>+   *  @param hDPI
>+   *  @param vDPI
>+   *  @param rotate
>+   *  @param useMediaBox
>+   *  @param crop
>+   *  @param printing
>+   *  @param sliceX
>+   *  @param sliceY
>+   *  @param sliceW
>+   *  @param sliceH
>+   *  @param abortCheckCbk
>+   *  @param abortCheckCbkData
>+   *  @param annotDisplayDecideCbk
>+   *  @param annotDisplayDecideCbkData
>+   */
>   void displayPageSlice(OutputDev *out, int page,
> 			double hDPI, double vDPI, int rotate, 
> 			GBool useMediaBox, GBool crop, GBool printing,
>@@ -166,82 +250,131 @@ public:
>                         GBool (*annotDisplayDecideCbk)(Annot *annot, void *user_data) = NULL,
>                         void *annotDisplayDecideCbkData = NULL);
> 
>-  // Find a page, given its object ID.  Returns page number, or 0 if
>-  // not found.
>+  /// Find a page, given its object ID.  Returns page number, or 0 if
>+  /// not found.
>   int findPage(int num, int gen) { return catalog->findPage(num, gen); }
> 
>-  // Returns the links for the current page, transferring ownership to
>-  // the caller.
>+  /// Returns the links for the current page, transferring ownership to
>+  /// the caller.
>   Links *getLinks(int page);
> 
>-  // Find a named destination.  Returns the link destination, or
>-  // NULL if <name> is not a destination.
>+  /// Find a named destination.  Returns the link destination, or
>+  /// NULL if <name> is not a destination.
>   LinkDest *findDest(GooString *name)
>     { return catalog->findDest(name); }
> 
>-  // Process the links for a page.
>+  /// Process the links for a page.
>   void processLinks(OutputDev *out, int page);
> 
> 
> #ifndef DISABLE_OUTLINE
>-  // Return the outline object.
>+  /// Return the outline object.
>   Outline *getOutline();
> #endif
> 
>-  // Is the file encrypted?
>+  /// Is the file encrypted?
>   GBool isEncrypted() { return xref->isEncrypted(); }
> 
>-  // Check various permissions.
>+  /// check for permission to print
>   GBool okToPrint(GBool ignoreOwnerPW = gFalse)
>     { return xref->okToPrint(ignoreOwnerPW); }
>+
>+  /// check for permission to print at high resolution
>   GBool okToPrintHighRes(GBool ignoreOwnerPW = gFalse)
>     { return xref->okToPrintHighRes(ignoreOwnerPW); }
>+
>+  /// check for permission to change the document
>   GBool okToChange(GBool ignoreOwnerPW = gFalse)
>     { return xref->okToChange(ignoreOwnerPW); }
>+
>+  /// check for permission to save a copy of the document
>   GBool okToCopy(GBool ignoreOwnerPW = gFalse)
>     { return xref->okToCopy(ignoreOwnerPW); }
>+
>+  /// check for permission to add notes to the document
>   GBool okToAddNotes(GBool ignoreOwnerPW = gFalse)
>     { return xref->okToAddNotes(ignoreOwnerPW); }
>+
>+  /// check for permission to enter data into forms on the document
>   GBool okToFillForm(GBool ignoreOwnerPW = gFalse)
>     { return xref->okToFillForm(ignoreOwnerPW); }
>+
>+  /// check for permission to run accessibility software on the document
>+  /// (i.e. screen reader)
>+  /**
>+   * @todo  Doc: the documentation for this is a guess
>+   * @param ignoreOwnerPW
>+   * @return
>+   */
>   GBool okToAccessibility(GBool ignoreOwnerPW = gFalse)
>     { return xref->okToAccessibility(ignoreOwnerPW); }
>+
>+  /// check for permission to assemble document
>   GBool okToAssemble(GBool ignoreOwnerPW = gFalse)
>     { return xref->okToAssemble(ignoreOwnerPW); }
> 
> 
>-  // Is this document linearized?
>+  /// Is this document linearized?
>+  /**
>+   *  a linearized PDF is one for which the first page information is moved
>+   *  to the beginning of the document so it can be rendered on the web while
>+   *  the rest of the document is loading
>+   */
>   GBool isLinearized();
> 
>-  // Return the document's Info dictionary (if any).
>+  /// Return the document's Info dictionary (if any).
>   Object *getDocInfo(Object *obj) { return xref->getDocInfo(obj); }
>   Object *getDocInfoNF(Object *obj) { return xref->getDocInfoNF(obj); }
> 
>-  // Return the PDF version specified by the file.
>+  /// Return the PDF version specified by the file .
>+  /**
>+   *  The major version is the number before the decimal point, i.e. "1"
>+   *  in "1.4"
>+   */
>   int getPDFMajorVersion() { return pdfMajorVersion; }
>+
>+  /// Return the PDF version specified by the file.
>+  /**
>+   *  The minor version is the number afterthe decimal point, i.e. "4"
>+   *  in "1.4"
>+   */
>   int getPDFMinorVersion() { return pdfMinorVersion; }
> 
>-  //Return the PDF ID in the trailer dictionary (if any).
>+  /// Return the PDF ID in the trailer dictionary (if any).
>   GBool getID(GooString *permanent_id, GooString *update_id);
> 
>-  // Save one page with another name.
>+  /// Save one page with another name.
>   int savePageAs(GooString *name, int pageNo);
>-  // Save this file with another name.
>+
>+  /// Save this file with another name.
>   int saveAs(GooString *name, PDFWriteMode mode=writeStandard);
>-  // Save this file in the given output stream.
>+
>+  /// Save this file in the given output stream.
>   int saveAs(OutStream *outStr, PDFWriteMode mode=writeStandard);
>-  // Save this file with another name without saving changes
>+
>+  /// Save this file with another name without saving changes
>   int saveWithoutChangesAs(GooString *name);
>-  // Save this file in the given output stream without saving changes
>+
>+  /// Save this file in the given output stream without saving changes
>   int saveWithoutChangesAs(OutStream *outStr);
> 
>-  // Return a pointer to the GUI (XPDFCore or WinPDFCore object).
>+  /// Return a pointer to the GUI (XPDFCore or WinPDFCore object).
>   void *getGUIData() { return guiData; }
> 
>-  // rewrite pageDict with MediaBox, CropBox and new page CTM
>+  /// rewrite pageDict for the specified page with a new MediaBox, CropBox and CTM
>+  /**
>+   *  @param pageNo     the page number to modify
>+   *  @param rotate     the new rotation for the page
>+   *  @param mediaBox   the new mediabox for the page (size of all content)
>+   *  @param cropBox    the new cropbox for the page  (size of cropped content)
>+   *  @param pageCTM    the new CTM for the page
>+   */
>   void replacePageDict(int pageNo, int rotate, PDFRectangle *mediaBox, PDFRectangle *cropBox, Object *pageCTM);
>+
>+  /// @todo Doc: needs documentation
>   void markPageObjects(Dict *pageDict, XRef *xRef, XRef *countRef, Guint numOffset);
>-  // write all objects used by pageDict to outStr
>+
>+  /// write all objects used by pageDict to outStr
>   Guint writePageObjects(OutStream *outStr, XRef *xRef, Guint numOffset);
>   static Guint writeObject (Object *obj, Ref *ref, OutStream* outStr, XRef *xref, Guint numOffset);
>   static void writeHeader(OutStream *outStr, int major, int minor);
>@@ -278,6 +411,7 @@ private:
>   // Get hints.
>   Hints *getHints();
> 
>+  /// Default constructor is private, only construct by loading a document
>   PDFDoc();
>   void init();
>   GBool setup(GooString *ownerPassword, GooString *userPassword);
>@@ -310,10 +444,16 @@ private:
> #endif
>   Page **pageCache;
> 
>+  /// if the document is loaded and no errors have occured then this will
>+  /// be true
>   GBool ok;
>+
>+  /// if the status of the document is not ok (i.e. ok false), the
>+  /// error code will be here
>   int errCode;
>-  //If there is an error opening the PDF file with fopen() in the constructor, 
>-  //then the POSIX errno will be here.
>+
>+  /// If there is an error opening the PDF file with fopen() in the constructor,
>+  /// then the POSIX errno will be here.
>   int fopenErrno;
> 
>   Guint startXRefPos;		// offset of last xref table
>diff --git a/poppler/PDFDocBuilder.h b/poppler/PDFDocBuilder.h
>index d6eccf5..46f5751 100644
>--- a/poppler/PDFDocBuilder.h
>+++ b/poppler/PDFDocBuilder.h
>@@ -22,6 +22,8 @@ class GooString;
> // constructing PDFDocs.
> //------------------------------------------------------------------------
> 
>+/// PDFDocBuilder is an abstract class that specifies the interface for
>+/// constructing PDFDocs.
> class PDFDocBuilder {
> 
> public:
>diff --git a/poppler/Page.h b/poppler/Page.h
>index 78cedc4..6c96b63 100644
>--- a/poppler/Page.h
>+++ b/poppler/Page.h
>@@ -49,15 +49,39 @@ class Form;
> 
> //------------------------------------------------------------------------
> 
>+/// Defines a rectangle (for use as an area or region)
>+/**
>+ *  The rectangle is stored as a pair of points
>+ *
>+ *  @verbatim
>+ *      (x1,y1)  ______________
>+ *              |              |
>+ *              |              |
>+ *              |______________|
>+ *                               (x2,y2)
>+ *  @endverbatim
>+ *
>+ *  @todo Doc: are rectangles (top/left,bottom/right) or (bottom/left,top/right)
>+ */
> class PDFRectangle {
> public:
>   double x1, y1, x2, y2;
> 
>+  /// construct a (0,0) (0,0) rectangle (note, this rectangle is invalid)
>   PDFRectangle() { x1 = y1 = x2 = y2 = 0; }
>+
>+  /// construct a rectangle from a pair of points
>   PDFRectangle(double x1A, double y1A, double x2A, double y2A)
>     { x1 = x1A; y1 = y1A; x2 = x2A; y2 = y2A; }
>+
>+  /// returns true the rectangle contains at least one nonzero entry
>   GBool isValid() { return x1 != 0 || y1 != 0 || x2 != 0 || y2 != 0; }
>+
>+  /// returns true if the query point (x,y) lies inside the rectangle
>   GBool contains(double x, double y) { return x1 <= x && x <= x2 && y1 <= y && y <= y2; }
>+
>+  /// calculate the intersection of this rectangle with another rectangle, and
>+  /// store the result in this rectangle
>   void clipTo(PDFRectangle *rect);
> };
> 
>@@ -65,6 +89,9 @@ public:
> // PageAttrs
> //------------------------------------------------------------------------
> 
>+
>+/// Stores attributes for a page including it's varius boxes and other
>+/// information
> class PageAttrs {
> public:
> 
>@@ -77,20 +104,85 @@ public:
>   ~PageAttrs();
> 
>   // Accessors.
>+
>+  /// return the media box defined for a page
>+  /**
>+   *    The media box is at least as large as all other boxes, and essentially
>+   *    defines the largest page boarder
>+   *
>+   *    @see http://www.prepressure.com/pdf/basics/page_boxes
>+   */
>   PDFRectangle *getMediaBox() { return &mediaBox; }
>+
>+  /// return the crop box defined for a page
>+  /**
>+   *    The crop box is the region to which the contents of the page should
>+   *    be clipped. This is the effective size of the page that is displayed
>+   *    by acrobat reader and during printing
>+   *
>+   *    @see http://www.prepressure.com/pdf/basics/page_boxes
>+   */
>   PDFRectangle *getCropBox() { return &cropBox; }
>+
>+  /// returns true if the page has a crop box
>   GBool isCropped() { return haveCropBox; }
>+
>+  /// return the bleed box for the page
>+  /**
>+   *    The bleed box is the size to which page contents should be clipped
>+   *    within a production environment. It is generally a few mm larger than
>+   *    the trim box (which is the intended size of the production document).
>+   *    I think the reason this is bigger is that you generally need to leave
>+   *    a margin for a physical printing device because it can't really drop
>+   *    ink on the very edge of the paper. Evidently, the bleed box is
>+   *    very often the same as the crop box.
>+   *
>+   *    @see http://www.prepressure.com/pdf/basics/page_boxes
>+   */
>   PDFRectangle *getBleedBox() { return &bleedBox; }
>+
>+  /// return the trim box
>+  /**
>+   *    The trim box defines the intended region of the finished page.
>+   *    Evidently it is used by a lot of production software as this is the
>+   *    region of the final product to be printed, and so if several
>+   *    documents are being layed out on the same sheet, this is the
>+   *    only size that matters for a given document.
>+   *
>+   *    @see http://www.prepressure.com/pdf/basics/page_boxes
>+   */
>   PDFRectangle *getTrimBox() { return &trimBox; }
>+
>+  /// return the art box
>+  /**
>+   *    The art box defines a region of the page which is of particular
>+   *    importance. Evidently it is rarely used in applications.
>+   *
>+   *    @see http://www.prepressure.com/pdf/basics/page_boxes
>+   */
>   PDFRectangle *getArtBox() { return &artBox; }
>+
>+  /// return the rotation of the page
>+  /**
>+   *    @todo Doc: figure out units (degrees?, enum?)
>+   */
>   int getRotate() { return rotate; }
>+
>+  /// return the last modified string of the page
>+  /**
>+   *    @todo Doc: is this a date-string or a user or what?
>+   */
>   GooString *getLastModified()
>     { return lastModified.isString()
> 	? lastModified.getString() : (GooString *)NULL; }
>+
>+
>   Dict *getBoxColorInfo()
>     { return boxColorInfo.isDict() ? boxColorInfo.getDict() : (Dict *)NULL; }
>   Dict *getGroup()
>     { return group.isDict() ? group.getDict() : (Dict *)NULL; }
>+
>+  /// return meta data stream for this page
>   Stream *getMetadata()
>     { return metadata.isStream() ? metadata.getStream() : (Stream *)NULL; }
>   Dict *getPieceInfo()
>@@ -101,7 +193,8 @@ public:
>   Dict *getResourceDict()
>     { return resources.isDict() ? resources.getDict() : (Dict *)NULL; }
> 
>-  // Clip all other boxes to the MediaBox.
>+
>+  /// Clip all other boxes to the MediaBox.
>   void clipBoxes();
> 
> private:
>@@ -128,6 +221,9 @@ private:
> // Page
> //------------------------------------------------------------------------
> 
>+
>+/// Object representing a single page from a PDF document, including it's
>+/// contents and all meta data
> class Page {
> public:
> 
>@@ -141,66 +237,153 @@ public:
>   GBool isOk() { return ok; }
> 
>   // Get page parameters.
>+  /// return the page number of this page within it's document
>   int getNum() { return num; }
>+
>+  /// return the media box for the page
>+  /**
>+   *    see PageAttrs::getMediaBox
>+   */
>   PDFRectangle *getMediaBox() { return attrs->getMediaBox(); }
>+
>+  /// return the crop box for this page
>+  /**
>+   *    see PageAttrs::getCropBox
>+   */
>   PDFRectangle *getCropBox() { return attrs->getCropBox(); }
>+
>+  /// return true if this page has a crop box
>   GBool isCropped() { return attrs->isCropped(); }
>+
>+  /// return the width of the media box
>+  /**
>+   *  @see PageAttrs::getMediaBox
>+   */
>   double getMediaWidth() 
>     { return attrs->getMediaBox()->x2 - attrs->getMediaBox()->x1; }
>+
>+  /// return the height of the media box
>+  /**
>+   *  @see PageAttrs::getMediaBox
>+   */
>   double getMediaHeight()
>     { return attrs->getMediaBox()->y2 - attrs->getMediaBox()->y1; }
>+
>+  /// return the width of the crop box
>+  /**
>+   *  @see PageAttrs::getCropBox
>+   */
>   double getCropWidth() 
>     { return attrs->getCropBox()->x2 - attrs->getCropBox()->x1; }
>+
>+  /// return the height of the crop box
>+  /**
>+   *  @see PageAttrs::getCropBox
>+   */
>   double getCropHeight()
>     { return attrs->getCropBox()->y2 - attrs->getCropBox()->y1; }
>+
>+  /// return the bleed box for the page
>+  /**
>+   *  @see PageAttrs::getBleedBox
>+   */
>   PDFRectangle *getBleedBox() { return attrs->getBleedBox(); }
>+
>+  /// return the trim box for the page
>+  /**
>+   *  @see PageAttrs::getTrimBox
>+   */
>   PDFRectangle *getTrimBox() { return attrs->getTrimBox(); }
>+
>+  /// return the art box for the page
>+  /**
>+   *  @see PageAttrs::getArtBox
>+   */
>   PDFRectangle *getArtBox() { return attrs->getArtBox(); }
>+
>+  /// get the rotation for the page
>+  /**
>+   *  @see PageAttrs::getRotate
>+   */
>   int getRotate() { return attrs->getRotate(); }
>+
>+  /// get the last modified info for the page
>+  /**
>+   *  @see PageAttrs::getLastModified
>+   */
>   GooString *getLastModified() { return attrs->getLastModified(); }
>+
>+  /// get the box color info for the page
>+  /**
>+   *  @see PageAttrs::getBoxColorInfo
>+   */
>   Dict *getBoxColorInfo() { return attrs->getBoxColorInfo(); }
>+
>+  /// get the group for the page
>+  /**
>+   *  @see PageAttrs::getGroup
>+   */
>   Dict *getGroup() { return attrs->getGroup(); }
>+
>+  /// get the meta data stream for the page
>+  /**
>+   *  @see PageAttrs::getMetadata
>+   */
>   Stream *getMetadata() { return attrs->getMetadata(); }
>+
>   Dict *getPieceInfo() { return attrs->getPieceInfo(); }
>   Dict *getSeparationInfo() { return attrs->getSeparationInfo(); }
>   PDFDoc *getDoc() { return doc; }
>   Ref getRef() { return pageRef; }
> 
>-  // Get resource dictionary.
>+  /// Get resource dictionary.
>   Dict *getResourceDict() { return attrs->getResourceDict(); }
> 
>-  // Get annotations array.
>+  /// Get annotations array.
>   Object *getAnnots(Object *obj) { return annotsObj.fetch(xref, obj); }
>-  // Add a new annotation to the page
>+
>+  /// Add a new annotation to the page
>   void addAnnot(Annot *annot);
>-  // Remove an existing annotation from the page
>+
>+  /// Remove an existing annotation from the page
>   void removeAnnot(Annot *annot);
> 
>-  // Return a list of links.
>+  /// Return a list of links.
>   Links *getLinks();
> 
>-  // Return a list of annots. It will be valid until the page is destroyed
>+  /// Return a list of annots. It will be valid until the page is destroyed
>   Annots *getAnnots();
> 
>-  // Get contents.
>+  /// Get contents.
>   Object *getContents(Object *obj) { return contents.fetch(xref, obj); }
> 
>-  // Get thumb.
>+  /// Get thumb.
>   Object *getThumb(Object *obj) { return thumb.fetch(xref, obj); }
>+
>+  /// load thumbnail image into the buffer at \p data
>+  /**
>+   * @param[out] data       the thumbnail image data
>+   * @param[out] width      the width of the thumbnail image
>+   * @param[out] height     the height of the thumbnail image
>+   * @param[out] rowstride  number of bytes in each row of the data (including
>+   *                        padding)
>+   *
>+   * @return true on success, false on failure
>+   */
>   GBool loadThumb(unsigned char **data, int *width, int *height, int *rowstride);
> 
>-  // Get transition.
>+  /// Get transition.
>   Object *getTrans(Object *obj) { return trans.fetch(xref, obj); }
> 
>-  // Get form.
>+  /// Get form.
>   FormPageWidgets *getFormWidgets();
> 
>-  // Get duration, the maximum length of time, in seconds,
>-  // that the page is displayed before the presentation automatically
>-  // advances to the next page
>+  /// Get duration, the maximum length of time, in seconds,
>+  /// that the page is displayed before the presentation automatically
>+  /// advances to the next page
>   double getDuration() { return duration; }
> 
>-  // Get actions
>+  /// Get actions
>   Object *getActions(Object *obj) { return actions.fetch(xref, obj); }
> 
>   Gfx *createGfx(OutputDev *out, double hDPI, double vDPI,
>@@ -210,7 +393,7 @@ public:
> 		 GBool (*abortCheckCbk)(void *data),
> 		 void *abortCheckCbkData);
> 
>-  // Display a page.
>+  /// Display a page.
>   void display(OutputDev *out, double hDPI, double vDPI,
> 	       int rotate, GBool useMediaBox, GBool crop,
> 	       GBool printing,
>@@ -219,7 +402,7 @@ public:
>                GBool (*annotDisplayDecideCbk)(Annot *annot, void *user_data) = NULL,
>                void *annotDisplayDecideCbkData = NULL);
> 
>-  // Display part of a page.
>+  /// Display part of a page.
>   void displaySlice(OutputDev *out, double hDPI, double vDPI,
> 		    int rotate, GBool useMediaBox, GBool crop,
> 		    int sliceX, int sliceY, int sliceW, int sliceH,
>@@ -238,26 +421,29 @@ public:
> 
>   void processLinks(OutputDev *out);
> 
>-  // Get the page's default CTM.
>+  /// Get the page's default CTM.
>+  /**
>+   *   @todo Doc: is CTM "Current Transformation Matrix?
>+   */
>   void getDefaultCTM(double *ctm, double hDPI, double vDPI,
> 		     int rotate, GBool useMediaBox, GBool upsideDown);
> 
> private:
> 
>   PDFDoc *doc;
>-  XRef *xref;			// the xref table for this PDF file
>-  Object pageObj;               // page dictionary
>-  Ref pageRef;                  // page reference
>-  int num;			// page number
>-  PageAttrs *attrs;		// page attributes
>-  Annots *annots;               // annotations
>-  Object annotsObj;		// annotations array
>-  Object contents;		// page contents
>-  Object thumb;			// page thumbnail
>-  Object trans;			// page transition
>-  Object actions;		// page addiction actions
>-  double duration;              // page duration
>-  GBool ok;			// true if page is valid
>+  XRef *xref;			///< the xref table for this PDF file
>+  Object pageObj;       ///< page dictionary
>+  Ref pageRef;          ///< page reference
>+  int num;			    ///< page number
>+  PageAttrs *attrs;		///< page attributes
>+  Annots *annots;       ///< annotations
>+  Object annotsObj;		///< annotations array
>+  Object contents;		///< page contents
>+  Object thumb;			///< page thumbnail
>+  Object trans;			///< page transition
>+  Object actions;		///< page addiction actions
>+  double duration;      ///< page duration
>+  GBool ok;			    ///< true if page is valid
> };
> 
> #endif
>diff --git a/poppler/XRef.h b/poppler/XRef.h
>index 148a5ce..2f2182e 100644
>--- a/poppler/XRef.h
>+++ b/poppler/XRef.h
>@@ -63,35 +63,46 @@ struct XRefEntry {
>   Object obj; //if this entry was updated, obj will contains the updated object
> };
> 
>+
>+/// An XRef is an item in the PDF Cross Reference Table
>+/**
>+ *   The xref is the index by which all of the indirect objects, in the PDF
>+ *   file, are located.  A single PDF file can contain multiple xref tables
>+ *   if the file has been incrementally saved or linearized.
>+ *
>+ *   @see http://labs.appligent.com/pdfblog/pdf_cross_reference_table.php
>+ */
> class XRef {
> public:
> 
>-  // Constructor, create an empty XRef, used for PDF writing
>+  /// Constructor, create an empty XRef, used for PDF writing
>   XRef();
>-  // Constructor, create an empty XRef but with info dict, used for PDF writing
>+
>+  /// Constructor, create an empty XRef but with info dict, used for PDF writing
>   XRef(Object *trailerDictA);
>-  // Constructor.  Read xref table from stream.
>+
>+  /// Constructor.  Read xref table from stream.
>   XRef(BaseStream *strA, Guint pos, Guint mainXRefEntriesOffsetA = 0, GBool *wasReconstructed = NULL, GBool reconstruct = false);
> 
>-  // Destructor.
>+  /// Destructor.
>   ~XRef();
> 
>-  // Is xref table valid?
>+  /// Is xref table valid?
>   GBool isOk() { return ok; }
> 
>-  // Is the last XRef section a stream or a table?
>+  /// Is the last XRef section a stream or a table?
>   GBool isXRefStream() { return xRefStream; }
> 
>-  // Get the error code (if isOk() returns false).
>+  /// Get the error code (if isOk() returns false).
>   int getErrorCode() { return errCode; }
> 
>-  // Set the encryption parameters.
>+  /// Set the encryption parameters.
>   void setEncryption(int permFlagsA, GBool ownerPasswordOkA,
> 		     Guchar *fileKeyA, int keyLengthA,
> 		     int encVersionA, int encRevisionA,
> 		     CryptAlgorithm encAlgorithmA);
> 
>-  // Is the file encrypted?
>+  /// Is the file encrypted?
>   GBool isEncrypted() { return encrypted; }
> 
>   // Check various permissions.
>@@ -105,28 +116,32 @@ public:
>   GBool okToAssemble(GBool ignoreOwnerPW = gFalse);
>   int getPermFlags() { return permFlags; }
> 
>-  // Get catalog object.
>+  /// Get catalog object.
>   Object *getCatalog(Object *obj) { return fetch(rootNum, rootGen, obj); }
> 
>-  // Fetch an indirect reference.
>+  /// Fetch an indirect reference.
>   Object *fetch(int num, int gen, Object *obj, int recursion = 0);
> 
>   // Return the document's Info dictionary (if any).
>   Object *getDocInfo(Object *obj);
>   Object *getDocInfoNF(Object *obj);
> 
>-  // Return the number of objects in the xref table.
>+  /// Return the number of objects in the xref table.
>   int getNumObjects() { return size; }
> 
>   // Return the catalog object reference.
>   int getRootNum() { return rootNum; }
>   int getRootGen() { return rootGen; }
> 
>-  // Get end position for a stream in a damaged file.
>-  // Returns false if unknown or file is not damaged.
>+  /// Get end position for a stream in a damaged file.
>+  /**
>+   * @param streamStart
>+   * @param streamEnd
>+   * @return false if unknown or file is not damaged.
>+   */
>   GBool getStreamEnd(Guint streamStart, Guint *streamEnd);
> 
>-  // Retuns the entry that belongs to the offset
>+  /// Returns the entry that belongs to the offset
>   int getNumEntry(Guint offset);
> 
>   // Direct access.
>@@ -139,9 +154,10 @@ public:
>   void removeIndirectObject(Ref r);
>   void add(int num, int gen,  Guint offs, GBool used);
> 
>-  // Output XRef table to stream
>+  /// Output XRef table to stream
>   void writeTableToFile(OutStream* outStr, GBool writeAllEntries);
>-  // Output XRef stream contents to GooString and fill trailerDict fields accordingly
>+
>+  /// Output XRef stream contents to GooString and fill trailerDict fields accordingly
>   void writeStreamToBuffer(GooString *stmBuf, Dict *xrefDict, XRef *xref);
> 
> private:
>-- 
>1.7.5.4
>
>
>From 472b86627e198128cb7f2622dd6acf14db36b29b Mon Sep 17 00:00:00 2001
>From: Josh Bialkowski <jbialk@mit.edu>
>Date: Tue, 10 Jul 2012 16:34:12 -0400
>Subject: [PATCH 2/2] fixed tab issues
>
>---
> poppler/Link.h |   18 +++++++++---------
> poppler/Page.h |   18 +++++++++---------
> 2 files changed, 18 insertions(+), 18 deletions(-)
>
>diff --git a/poppler/Link.h b/poppler/Link.h
>index 64476ed..295d5b4 100644
>--- a/poppler/Link.h
>+++ b/poppler/Link.h
>@@ -46,17 +46,17 @@ class Annots;
> 
> /// Enumerates the types of a PDF hyper-reference (link)
> enum LinkActionKind {
>-  actionGoTo,			///< go to destination
>-  actionGoToR,			///< go to destination in new file
>-  actionLaunch,			///< launch app (or open document)
>-  actionURI,			///< URI
>-  actionNamed,			///< named action
>-  actionMovie,			///< movie action
>+  actionGoTo,           ///< go to destination
>+  actionGoToR,          ///< go to destination in new file
>+  actionLaunch,         ///< launch app (or open document)
>+  actionURI,            ///< URI
>+  actionNamed,          ///< named action
>+  actionMovie,          ///< movie action
>   actionRendition,
>-  actionSound,			///< sound action
>-  actionJavaScript,		///< JavaScript action
>+  actionSound,          ///< sound action
>+  actionJavaScript,     ///< JavaScript action
>   actionOCGState,       ///< Set-OCG-State action
>-  actionUnknown			///< anything else
>+  actionUnknown         ///< anything else
> };
> 
> class LinkAction {
>diff --git a/poppler/Page.h b/poppler/Page.h
>index 6c96b63..993f76c 100644
>--- a/poppler/Page.h
>+++ b/poppler/Page.h
>@@ -431,19 +431,19 @@ public:
> private:
> 
>   PDFDoc *doc;
>-  XRef *xref;			///< the xref table for this PDF file
>+  XRef *xref;           ///< the xref table for this PDF file
>   Object pageObj;       ///< page dictionary
>   Ref pageRef;          ///< page reference
>-  int num;			    ///< page number
>-  PageAttrs *attrs;		///< page attributes
>+  int num;              ///< page number
>+  PageAttrs *attrs;     ///< page attributes
>   Annots *annots;       ///< annotations
>-  Object annotsObj;		///< annotations array
>-  Object contents;		///< page contents
>-  Object thumb;			///< page thumbnail
>-  Object trans;			///< page transition
>-  Object actions;		///< page addiction actions
>+  Object annotsObj;     ///< annotations array
>+  Object contents;      ///< page contents
>+  Object thumb;         ///< page thumbnail
>+  Object trans;         ///< page transition
>+  Object actions;       ///< page addiction actions
>   double duration;      ///< page duration
>-  GBool ok;			    ///< true if page is valid
>+  GBool ok;             ///< true if page is valid
> };
> 
> #endif
>-- 
>1.7.5.4
>

Actions: View | Splinter Review

Attachments on bug 54279: 66366

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.