From 227c04bc9236c3961d6cfb52b81c6d966415f1b9 Mon Sep 17 00:00:00 2001
From: Marius Volkhart <mariusvolkhart@apache.org>
Date: Fri, 1 Oct 2021 12:18:01 +0000
Subject: [PATCH] Consolidate spreadsheet PictureData javadocs

If docs for an implementation were identical or substantially similar to that of the interface, I removed them from the implementation, as Javadocs inherit automatically.

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1893780 13f79535-47bb-0310-9956-ffa450edef68
---
 .../poi/xssf/usermodel/XSSFPictureData.java    | 18 ++----------------
 .../poi/hssf/usermodel/HSSFPictureData.java    | 10 ----------
 .../apache/poi/ss/usermodel/PictureData.java   |  5 +++--
 3 files changed, 5 insertions(+), 28 deletions(-)

diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFPictureData.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFPictureData.java
index ecdb1de04c..d84a26c5d7 100644
--- a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFPictureData.java
+++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFPictureData.java
@@ -93,26 +93,12 @@ public class XSSFPictureData extends POIXMLDocumentPart implements PictureData {
         }
     }
 
-    /**
-     * Suggests a file extension for this image.
-     *
-     * @return the file extension.
-     */
+    @Override
     public String suggestFileExtension() {
         return getPackagePart().getPartName().getExtension();
     }
 
-    /**
-     * Return an integer constant that specifies type of this picture
-     *
-     * @return an integer constant that specifies type of this picture 
-     * @see org.apache.poi.ss.usermodel.Workbook#PICTURE_TYPE_EMF
-     * @see org.apache.poi.ss.usermodel.Workbook#PICTURE_TYPE_WMF
-     * @see org.apache.poi.ss.usermodel.Workbook#PICTURE_TYPE_PICT
-     * @see org.apache.poi.ss.usermodel.Workbook#PICTURE_TYPE_JPEG
-     * @see org.apache.poi.ss.usermodel.Workbook#PICTURE_TYPE_PNG
-     * @see org.apache.poi.ss.usermodel.Workbook#PICTURE_TYPE_DIB
-     */
+    @Override
     public int getPictureType(){
         String contentType = getPackagePart().getContentType();
         for (int i = 0; i < RELATIONS.length; i++) {
diff --git a/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFPictureData.java b/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFPictureData.java
index 802bf28e30..702d3602e2 100644
--- a/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFPictureData.java
+++ b/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFPictureData.java
@@ -102,9 +102,6 @@ public class HSSFPictureData implements PictureData
         }
     }
 
-    /**
-     * Returns the mime type for the image
-     */
     @Override
     public String getMimeType() {
        switch (EscherRecordTypes.forTypeID(blip.getRecordId())) {
@@ -130,13 +127,6 @@ public class HSSFPictureData implements PictureData
     /**
      * @return the POI internal image type, 0 if unknown image type (was -1 prior to 5.0.0 but
      * that was inconsistent with other {@link PictureData} implementations)
-     *
-     * @see Workbook#PICTURE_TYPE_DIB
-     * @see Workbook#PICTURE_TYPE_EMF
-     * @see Workbook#PICTURE_TYPE_JPEG
-     * @see Workbook#PICTURE_TYPE_PICT
-     * @see Workbook#PICTURE_TYPE_PNG
-     * @see Workbook#PICTURE_TYPE_WMF
      */
     @Override
     public int getPictureType() {
diff --git a/poi/src/main/java/org/apache/poi/ss/usermodel/PictureData.java b/poi/src/main/java/org/apache/poi/ss/usermodel/PictureData.java
index 67d3cefcd1..d2d8027dff 100644
--- a/poi/src/main/java/org/apache/poi/ss/usermodel/PictureData.java
+++ b/poi/src/main/java/org/apache/poi/ss/usermodel/PictureData.java
@@ -29,7 +29,8 @@ public interface PictureData {
     /**
      * Suggests a file extension for this image.
      *
-     * @return the file extension.
+     * @return the file extension, without a leading {@code .}. Never {@code null}, but will be empty if the extension
+     * is unknown or if the file backing these data does not have an extension.
      */
     String suggestFileExtension();
 
@@ -39,7 +40,7 @@ public interface PictureData {
     String getMimeType();
     
     /**
-     * @return the POI internal image type, 0 if unknown image type
+     * @return the POI internal image type, {@code 0} if unknown image type
      *
      * @see Workbook#PICTURE_TYPE_DIB
      * @see Workbook#PICTURE_TYPE_EMF