You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pdfbox.apache.org by le...@apache.org on 2022/11/07 06:46:18 UTC
svn commit: r1905116 - in /pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel: ./ encryption/ font/
Author: lehmi
Date: Mon Nov 7 06:46:18 2022
New Revision: 1905116
URL: http://svn.apache.org/viewvc?rev=1905116&view=rev
Log:
PDFBOX-4892: fix javadoc
Modified:
pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDResources.java
pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/encryption/ProtectionPolicy.java
pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/encryption/SecurityHandler.java
pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/CIDFontMapping.java
pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontCache.java
pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontInfo.java
pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontMapper.java
pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontMapping.java
pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontProvider.java
pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/PDCIDFont.java
pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/PDFontLike.java
pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/PDVectorFont.java
Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDResources.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDResources.java?rev=1905116&r1=1905115&r2=1905116&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDResources.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDResources.java Mon Nov 7 06:46:18 2022
@@ -214,6 +214,7 @@ public final class PDResources implement
* Returns true if the given color space name exists in these resources.
*
* @param name Name of the color space resource.
+ * @return true if the given color space name exists in these resources, otherwise false
*/
public boolean hasColorSpace(COSName name)
{
@@ -824,6 +825,8 @@ public final class PDResources implement
/**
* Returns the resource cache associated with the Resources, or null if there is none.
+ *
+ * @return the resource cache associated with the resources, or null
*/
public ResourceCache getResourceCache()
{
Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/encryption/ProtectionPolicy.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/encryption/ProtectionPolicy.java?rev=1905116&r1=1905115&r2=1905116&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/encryption/ProtectionPolicy.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/encryption/ProtectionPolicy.java Mon Nov 7 06:46:18 2022
@@ -76,11 +76,10 @@ public abstract class ProtectionPolicy
}
/**
- * Set whether AES encryption is preferred when several encryption methods are available for the
- * chosen key length. The default is false. This setting is only relevant if the key length is
- * 128 bits.
+ * Set whether AES encryption is preferred when several encryption methods are available for the chosen key length.
+ * The default is false. This setting is only relevant if the key length is 128 bits.
*
- * @param preferAES
+ * @param preferAES indicates whether AES encryption is preferred or not
*/
public void setPreferAES(boolean preferAES)
{
Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/encryption/SecurityHandler.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/encryption/SecurityHandler.java?rev=1905116&r1=1905115&r2=1905116&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/encryption/SecurityHandler.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/encryption/SecurityHandler.java Mon Nov 7 06:46:18 2022
@@ -675,8 +675,9 @@ public abstract class SecurityHandler<T_
}
/**
- * Getter of the property <tt>keyLength</tt>.
- * @return Returns the keyLength in bits.
+ * Getter of the property keyLength.
+ *
+ * @return Returns the keyLength in bits.
*/
public int getKeyLength()
{
@@ -684,9 +685,9 @@ public abstract class SecurityHandler<T_
}
/**
- * Setter of the property <tt>keyLength</tt>.
+ * Setter of the property keyLength.
*
- * @param keyLen The keyLength to set in bits.
+ * @param keyLen The keyLength to set in bits.
*/
public void setKeyLength(int keyLen)
{
Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/CIDFontMapping.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/CIDFontMapping.java?rev=1905116&r1=1905115&r2=1905116&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/CIDFontMapping.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/CIDFontMapping.java Mon Nov 7 06:46:18 2022
@@ -38,6 +38,8 @@ public final class CIDFontMapping extend
/**
* Returns a TrueType font when isCIDFont() is true, otherwise null.
+ *
+ * @return the mapped TrueType font or null
*/
public FontBoxFont getTrueTypeFont()
{
@@ -46,6 +48,8 @@ public final class CIDFontMapping extend
/**
* Returns true if this is a CID font.
+ *
+ * @return true if the mapped font is a CID font
*/
public boolean isCIDFont()
{
Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontCache.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontCache.java?rev=1905116&r1=1905115&r2=1905116&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontCache.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontCache.java Mon Nov 7 06:46:18 2022
@@ -34,6 +34,9 @@ public final class FontCache
/**
* Adds the given FontBox font to the cache.
+ *
+ * @param info the FontInfo to be used as key
+ * @param font the font to be cached
*/
public void addFont(FontInfo info, FontBoxFont font)
{
@@ -42,6 +45,10 @@ public final class FontCache
/**
* Returns the FontBox font associated with the given FontInfo.
+ *
+ * @param info the FontInfo of the cached font
+ *
+ * @return the cached font if available, otherwise null
*/
public FontBoxFont getFont(FontInfo info)
{
Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontInfo.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontInfo.java?rev=1905116&r1=1905115&r2=1905116&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontInfo.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontInfo.java Mon Nov 7 06:46:18 2022
@@ -28,37 +28,51 @@ public abstract class FontInfo
{
/**
* Returns the PostScript name of the font.
+ *
+ * @return the PostScript name of the font
*/
public abstract String getPostScriptName();
/**
* Returns the font's format.
+ *
+ * @return the format of the font
*/
public abstract FontFormat getFormat();
/**
- * Returns the CIDSystemInfo associated with the font, if any.
+ * Returns the CIDSystemInfo associated with the font, if present.
+ *
+ * @return the CIDSystemInof of the font if any
*/
public abstract CIDSystemInfo getCIDSystemInfo();
/**
- * Returns a new FontBox font instance for the font. Implementors of this method must not
- * cache the return value of this method unless doing so via the current {@link FontCache}.
+ * Returns a new FontBox font instance for the font. Implementors of this method must not cache the return value of
+ * this method unless doing so via the current {@link FontCache}.
+ *
+ * @return a new FontBox instance of the font
*/
public abstract FontBoxFont getFont();
/**
* Returns the sFamilyClass field of the "OS/2" table, or -1.
+ *
+ * @return the FamilyClass of the font
*/
public abstract int getFamilyClass();
/**
* Returns the usWeightClass field of the "OS/2" table, or -1.
+ *
+ * @return the WeightClass of the font
*/
public abstract int getWeightClass();
/**
* Returns the usWeightClass field as a Panose Weight.
+ *
+ * @return the WeightClass of the font as Panose weight
*/
final int getWeightClassAsPanose()
{
@@ -82,16 +96,22 @@ public abstract class FontInfo
/**
* Returns the ulCodePageRange1 field of the "OS/2" table, or 0.
+ *
+ * @return the CodePageRange1 of the font if present
*/
public abstract int getCodePageRange1();
/**
* Returns the ulCodePageRange2 field of the "OS/2" table, or 0.
+ *
+ * @return the CodePageRange2 of the font if present
*/
public abstract int getCodePageRange2();
/**
* Returns the ulCodePageRange1 and ulCodePageRange1 field of the "OS/2" table, or 0.
+ *
+ * @return the CodePageRange of the font
*/
final long getCodePageRange()
{
@@ -102,11 +122,15 @@ public abstract class FontInfo
/**
* Returns the macStyle field of the "head" table, or -1.
+ *
+ * @return the MacStyle of the font
*/
public abstract int getMacStyle();
/**
* Returns the Panose classification of the font, if any.
+ *
+ * @return the PanoseClassification of the font
*/
public abstract PDPanoseClassification getPanose();
Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontMapper.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontMapper.java?rev=1905116&r1=1905115&r2=1905116&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontMapper.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontMapper.java Mon Nov 7 06:46:18 2022
@@ -30,24 +30,33 @@ public interface FontMapper
/**
* Finds a TrueType font with the given PostScript name, or a suitable substitute, or null.
*
+ * @param baseFont PostScript name of the mapped font
* @param fontDescriptor FontDescriptor
+ *
+ * @return the mapped TrueType font or null
*/
FontMapping<TrueTypeFont> getTrueTypeFont(String baseFont, PDFontDescriptor fontDescriptor);
/**
- * Finds a font with the given PostScript name, or a suitable substitute, or null. This allows
- * any font to be substituted with a PFB, TTF or OTF.
+ * Finds a font with the given PostScript name, or a suitable substitute, or null. This allows any font to be
+ * substituted with a PFB, TTF or OTF.
*
+ * @param baseFont PostScript name of the mapped font
* @param fontDescriptor the FontDescriptor of the font to find
+ *
+ * @return the mapped FontBox font or null
*/
FontMapping<FontBoxFont> getFontBoxFont(String baseFont, PDFontDescriptor fontDescriptor);
/**
- * Finds a CFF CID-Keyed font with the given PostScript name, or a suitable substitute, or null.
- * This method can also map CJK fonts via their CIDSystemInfo (ROS).
+ * Finds a CFF CID-Keyed font with the given PostScript name, or a suitable substitute, or null. This method can
+ * also map CJK fonts via their CIDSystemInfo (ROS).
*
+ * @param baseFont PostScript name of the mapped font
* @param fontDescriptor FontDescriptor
* @param cidSystemInfo the CID system info, e.g. "Adobe-Japan1", if any.
+ *
+ * @return the mapped CIDFont font or null
*/
CIDFontMapping getCIDFont(String baseFont, PDFontDescriptor fontDescriptor,
PDCIDSystemInfo cidSystemInfo);
Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontMapping.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontMapping.java?rev=1905116&r1=1905115&r2=1905116&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontMapping.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontMapping.java Mon Nov 7 06:46:18 2022
@@ -37,6 +37,8 @@ public class FontMapping<T extends FontB
/**
* Returns the mapped, FontBox font. This is never null.
+ *
+ * @return the mapped font
*/
public T getFont()
{
@@ -44,8 +46,10 @@ public class FontMapping<T extends FontB
}
/**
- * Returns true if the mapped font is a fallback, i.e. a substitute based on basic font style,
- * such as bold/italic, rather than font name.
+ * Returns true if the mapped font is a fallback, i.e. a substitute based on basic font style, such as bold/italic,
+ * rather than font name.
+ *
+ * @return true if the mapped font is a fallback
*/
public boolean isFallback()
{
Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontProvider.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontProvider.java?rev=1905116&r1=1905115&r2=1905116&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontProvider.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/FontProvider.java Mon Nov 7 06:46:18 2022
@@ -26,13 +26,17 @@ import java.util.List;
public abstract class FontProvider
{
/**
- * Returns a string containing debugging information. This will be written to the log if no
- * suitable fonts are found and no fallback fonts are available. May be null.
+ * Returns a string containing debugging information. This will be written to the log if no suitable fonts are found
+ * and no fallback fonts are available. May be null.
+ *
+ * @return string with debug information or null
*/
public abstract String toDebugString();
/**
* Returns a list of information about fonts on the system.
+ *
+ * @return a list of FntInfo instances for all fonts on the system
*/
public abstract List<? extends FontInfo> getFontInfo();
}
Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/PDCIDFont.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/PDCIDFont.java?rev=1905116&r1=1905115&r2=1905116&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/PDCIDFont.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/PDCIDFont.java Mon Nov 7 06:46:18 2022
@@ -354,6 +354,8 @@ public abstract class PDCIDFont implemen
/**
* Returns the CIDSystemInfo, or null if it is missing (which isn't allowed but could happen).
+ *
+ * @return the CIDSystemInfo, or null
*/
public PDCIDSystemInfo getCIDSystemInfo()
{
@@ -374,7 +376,7 @@ public abstract class PDCIDFont implemen
*
* @param code character code
* @return GID
- * @throws java.io.IOException
+ * @throws java.io.IOException if the mapping could not be read
*/
public abstract int codeToGID(int code) throws IOException;
Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/PDFontLike.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/PDFontLike.java?rev=1905116&r1=1905115&r2=1905116&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/PDFontLike.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/PDFontLike.java Mon Nov 7 06:46:18 2022
@@ -31,21 +31,31 @@ public interface PDFontLike
{
/**
* Returns the name of this font, either the PostScript "BaseName" or the Type 3 "Name".
+ *
+ * @return the name of the font
*/
String getName();
/**
* Returns the font descriptor, may be null.
+ *
+ * @return the font descriptor or null
*/
PDFontDescriptor getFontDescriptor();
/**
* Returns the font matrix, which represents the transformation from glyph space to text space.
+ *
+ * @return the font matrix
*/
Matrix getFontMatrix();
/**
* Returns the font's bounding box.
+ *
+ * @return the bounding box
+ *
+ * @throws IOException if the bounding box could not be read
*/
BoundingBox getBoundingBox() throws IOException;
@@ -60,41 +70,45 @@ public interface PDFontLike
Vector getPositionVector(int code);
/**
- * Returns the height of the given character, in glyph space. This can be expensive to
- * calculate. Results are only approximate.<p>
+ * Returns the height of the given character, in glyph space. This can be expensive to calculate. Results are only
+ * approximate.
+ * <p>
*
- * Warning: This method is deprecated in PDFBox 2.0 because there is no meaningful value
- * which it can return. The {@link #getWidth(int)} method returns the advance width of a glyph,
- * but there is no corresponding advance height. The logical height of a character is the same
- * for every character in a font, so if you want that, retrieve the font bbox's height.
- * Otherwise if you want the visual bounds of the glyph then call getPath(..) on the appropriate
- * PDFont subclass to retrieve the glyph outline as a GeneralPath. See the cyan rectangles in
- * the <b>DrawPrintTextLocations.java</b> example to see this in action.
+ * Warning: This method is deprecated in PDFBox 2.0 because there is no meaningful value which it can return. The
+ * {@link #getWidth(int)} method returns the advance width of a glyph, but there is no corresponding advance height.
+ * The logical height of a character is the same for every character in a font, so if you want that, retrieve the
+ * font bbox's height. Otherwise if you want the visual bounds of the glyph then call getPath(..) on the appropriate
+ * PDFont subclass to retrieve the glyph outline as a GeneralPath. See the cyan rectangles in the
+ * <b>DrawPrintTextLocations.java</b> example to see this in action.
*
* @param code character code
- * @deprecated Use
- * {@link #getBoundingBox() getBoundingBox()}.{@link BoundingBox#getHeight() getHeight()}
- * instead.
+ * @return the height of the given character
+ *
+ * @deprecated Use {@link #getBoundingBox() getBoundingBox()}.{@link BoundingBox#getHeight() getHeight()} instead.
*/
@Deprecated
float getHeight(int code) throws IOException;
/**
- * Returns the advance width of the given character, in glyph space.<p>
+ * Returns the advance width of the given character, in glyph space.
+ * <p>
*
- * If you want the visual bounds of the glyph then call getPath(..) on the appropriate
- * PDFont subclass to retrieve the glyph outline as a GeneralPath instead. See the cyan
- * rectangles in the <b>DrawPrintTextLocations.java</b> example to see this in action.
+ * If you want the visual bounds of the glyph then call getPath(..) on the appropriate PDFont subclass to retrieve
+ * the glyph outline as a GeneralPath instead. See the cyan rectangles in the <b>DrawPrintTextLocations.java</b>
+ * example to see this in action.
*
* @param code character code
+ * @return the width of the given character
*/
float getWidth(int code) throws IOException;
/**
- * Returns true if the Font dictionary specifies an explicit width for the given glyph.
- * This includes Width, W but not default widths entries.
+ * Returns true if the Font dictionary specifies an explicit width for the given glyph. This includes Width, W but
+ * not default widths entries.
*
* @param code character code
+ * @return true if the Font dictionary specifies an explicit width for the given glyph
+ *
* @throws IOException if the font could not be read
*/
boolean hasExplicitWidth(int code) throws IOException;
@@ -110,11 +124,15 @@ public interface PDFontLike
/**
* Returns true if the font file is embedded in the PDF.
+ *
+ * @return true if the font file is embedded in the PDF
*/
boolean isEmbedded();
/**
* Returns true if the embedded font file is damaged.
+ *
+ * @return true if the embedded font file is damaged
*/
boolean isDamaged();
Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/PDVectorFont.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/PDVectorFont.java?rev=1905116&r1=1905115&r2=1905116&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/PDVectorFont.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/PDVectorFont.java Mon Nov 7 06:46:18 2022
@@ -31,16 +31,17 @@ public interface PDVectorFont
* Returns the glyph path for the given character code.
*
* @param code character code in a PDF. Not to be confused with unicode.
+ * @return the glyph path for the given character code
* @throws java.io.IOException if the font could not be read
*/
GeneralPath getPath(int code) throws IOException;
/**
- * Returns the normalized glyph path for the given character code in a PDF. The resulting path
- * is normalized to the PostScript 1000 unit square, and fallback glyphs are returned where
- * appropriate, e.g. for missing glyphs.
+ * Returns the normalized glyph path for the given character code in a PDF. The resulting path is normalized to the
+ * PostScript 1000 unit square, and fallback glyphs are returned where appropriate, e.g. for missing glyphs.
*
* @param code character code in a PDF. Not to be confused with unicode.
+ * @return the normalized glyph path for the given character code
* @throws java.io.IOException if the font could not be read
*/
GeneralPath getNormalizedPath(int code) throws IOException;
@@ -49,6 +50,7 @@ public interface PDVectorFont
* Returns true if this font contains a glyph for the given character code in a PDF.
*
* @param code character code in a PDF. Not to be confused with unicode.
+ * @return true if this font contains a glyph for the given character code
*/
boolean hasGlyph(int code) throws IOException;
}