From 8bf5d32a6f8af81d2da5977629d3f35e7af46872 Mon Sep 17 00:00:00 2001 From: SIX Douglas Date: Sat, 22 Oct 2022 19:20:59 +0200 Subject: [PATCH] feat update javadoc on document class --- .../main/java/com/lowagie/text/Document.java | 216 +++++++++++------- 1 file changed, 135 insertions(+), 81 deletions(-) diff --git a/openpdf/src/main/java/com/lowagie/text/Document.java b/openpdf/src/main/java/com/lowagie/text/Document.java index f17935448..a943e6b8a 100644 --- a/openpdf/src/main/java/com/lowagie/text/Document.java +++ b/openpdf/src/main/java/com/lowagie/text/Document.java @@ -214,14 +214,14 @@ private static String getVersionNumber() { // constructor /** - * Constructs a new Document -object. + * Constructs a new Document -object with the default page size as PageSize.A4 . */ public Document() { this(PageSize.A4); } /** - * Constructs a new Document -object. + * Constructs a new Document -object using the given rectangle as page size and default margin of 36. * * @param pageSize * the pageSize @@ -329,14 +329,17 @@ public void open() { listener.open(); } } - + /** - * Sets the pagesize. - * + * Sets the pagesize. + *

+ * This change will be effective starting from the next page. If you want to change the page size of + * the first page, you need to set it before opening the document. + * * @param pageSize * the new pagesize - * @return a boolean - */ + * @return a boolean + */ public boolean setPageSize(Rectangle pageSize) { this.pageSize = pageSize; for (DocListener listener : listeners) { @@ -344,20 +347,19 @@ public boolean setPageSize(Rectangle pageSize) { } return true; } - + /** - * Sets the margins. - * - * @param marginLeft - * the margin on the left - * @param marginRight - * the margin on the right - * @param marginTop - * the margin on the top - * @param marginBottom - * the margin on the bottom - * @return a boolean - */ + * Sets the margins. + *

+ * This change will be effective starting from the next page. If you want to change margins on + * the first page, you need to set it before opening the document. + * + * @param marginLeft the margin on the left + * @param marginRight the margin on the right + * @param marginTop the margin on the top + * @param marginBottom the margin on the bottom + * @return a boolean + */ public boolean setMargins(float marginLeft, float marginRight, float marginTop, float marginBottom) { this.marginLeft = marginLeft; @@ -372,11 +374,12 @@ public boolean setMargins(float marginLeft, float marginRight, } /** - * Signals that an new page has to be started. - * + * Signals to all listeners, that a new page has to be started. + * New pages can only be added on already opened and not yet closed documents. + * * @return true if the page was added, false * if not. - */ + */ public boolean newPage() { if (!open || close) { return false; @@ -443,6 +446,8 @@ public void resetFooter() { /** * Sets the page number to 0. + *

+ * This change will be effective starting from the next page. */ public void resetPageCount() { pageN = 0; @@ -453,6 +458,10 @@ public void resetPageCount() { /** * Sets the page number. + *

+ * This change will be effective starting from the next page. + *

+ * The page number of the next new page will be: pageN + 1 * * @param pageN the new page number */ @@ -490,17 +499,16 @@ public void close() { } // methods concerning the header or some meta information - + /** - * Adds a user defined header to the document. - * - * @param name - * the name of the header - * @param content - * the content of the header - * @return true if successful, false otherwise - */ - + * Adds a user defined header to the document. + *

+ * Shortcut method to call: add(new Header(name, content)) + * + * @param name the name of the header + * @param content the content of the header + * @return true if successful, false otherwise + */ public boolean addHeader(String name, String content) { try { return add(new Header(name, content)); @@ -508,15 +516,20 @@ public boolean addHeader(String name, String content) { throw new ExceptionConverter(de); } } - + /** - * Adds the title to a Document. - * - * @param title - * the title - * @return true if successful, false otherwise - */ - + * Adds the title to a Document. + *

+ * In case of a PDF this will be visible in the document properties panel. + *

+ * In case of a HTML file this will be visible as the title meta tag in the + * HEAD part of the file. + *

+ * Shortcut method to call: add(new Meta(Element.TITLE, title)) + * + * @param title the title + * @return true if successful, false otherwise + */ public boolean addTitle(String title) { try { return add(new Meta(Element.TITLE, title)); @@ -524,15 +537,18 @@ public boolean addTitle(String title) { throw new ExceptionConverter(de); } } - + /** - * Adds the subject to a Document. - * - * @param subject - * the subject - * @return true if successful, false otherwise - */ - + * Adds the subject to a Document. + *

+ * In case of a PDF this will be visible in the document properties panel. + *

+ * In case of a HTML file this will be visible as the subject meta tag in the + * HEAD part of the file. + * + * @param subject the subject + * @return true if successful, false otherwise + */ public boolean addSubject(String subject) { try { return add(new Meta(Element.SUBJECT, subject)); @@ -540,15 +556,18 @@ public boolean addSubject(String subject) { throw new ExceptionConverter(de); } } - + /** - * Adds the keywords to a Document. - * - * @param keywords - * adds the keywords to the document - * @return true if successful, false otherwise - */ - + * Adds the keywords to a Document. + *

+ * In case of a PDF this will be visible in the document properties panel. + *

+ * In case of a HTML file this will be visible as the keywords meta tag in the + * HEAD part of the file. + * + * @param keywords adds the keywords to the document + * @return true if successful, false otherwise + */ public boolean addKeywords(String keywords) { try { return add(new Meta(Element.KEYWORDS, keywords)); @@ -556,15 +575,18 @@ public boolean addKeywords(String keywords) { throw new ExceptionConverter(de); } } - + /** - * Adds the author to a Document. - * - * @param author - * the name of the author - * @return true if successful, false otherwise - */ - + * Adds the author to a Document. + *

+ * In case of a PDF this will be visible in the document properties panel. + *

+ * In case of a HTML file this will be visible as the author meta tag in the + * HEAD part of the file. + * + * @param author the name of the author + * @return true if successful, false otherwise + */ public boolean addAuthor(String author) { try { return add(new Meta(Element.AUTHOR, author)); @@ -574,13 +596,16 @@ public boolean addAuthor(String author) { } /** - * Adds the creator to a Document. - * + * Adds the creator to a Document. + *

+ * In case of a PDF this will be visible in the document properties panel. + *

+ * In case of a HTML file this will be visible as comment in the HEAD part of the file. + * * @param creator * the name of the creator - * @return true if successful, false otherwise - */ - + * @return true if successful, false otherwise + */ public boolean addCreator(String creator) { try { return add(new Meta(Element.CREATOR, creator)); @@ -590,17 +615,27 @@ public boolean addCreator(String creator) { } /** - * Adds the producer to a Document. - * - * @return true if successful, false otherwise - */ - + * Adds the producer to a Document. + *

+ * In case of a PDF this will be visible in the document properties panel. + *

+ * In case of a HTML file this will be visible as comment in the HEAD part of the file. + * + * @return true if successful, false otherwise + */ public boolean addProducer() { return this.addProducer(getVersion()); } /** * Adds the provided value as the producer to a Document. + *

+ * The default producer is OpenPDF XX.YY.ZZ where XX.YY.ZZ is the version of the OpenPDF + * library used to produce the document + *

+ * In case of a PDF this will be visible in the document properties panel. + *

+ * In case of a HTML file this will be visible as comment in the HEAD part of the file. * * @param producer new producer line value * @return true if successful, false otherwise @@ -608,13 +643,16 @@ public boolean addProducer() { public boolean addProducer(final String producer) { return add(new Meta(Element.PRODUCER, producer)); } - + /** - * Adds the current date and time to a Document. - * - * @return true if successful, false otherwise - */ - + * Adds the current date and time to a Document. + *

+ * In case of a PDF this will be visible in the document properties panel. + *

+ * In case of a HTML file this will be visible as comment in the HEAD part of the file. + * + * @return true if successful, false otherwise + */ public boolean addCreationDate() { try { /* bugfix by 'taqua' (Thomas) */ @@ -911,10 +949,26 @@ public boolean isMarginMirroring() { return marginMirroring; } + /** + * The new document language. + * This language is used in FopGlyphProcessor to determine which glyphs are to be substituted. + *

+ * The default "dflt" means that all glyphs which can be replaced will be substituted. + * + * @param documentLanguage the wanted language + */ public void setDocumentLanguage(String documentLanguage) { this.documentLanguage = documentLanguage; } + /** + * The default language of the document. Can be set to values like "en_US". This language is used in + * FopGlyphProcessor to determine which glyphs are to be substituted. + *

+ * The default "dflt" means that all glyphs which can be replaced will be substituted. + * + * @return the current document language + */ public String getDocumentLanguage() { return documentLanguage; }