🎨 Optimize javadoc

Kururu-Q · Oct 29, 2017 · 819abb5 · 819abb5
1 parent 179e0bc
commit 819abb5
Show file tree

Hide file tree

Showing 23 changed files with 267 additions and 112 deletions.
diff --git a/docs/logs/log_2.6.0_p1.md b/docs/logs/log_2.6.0_p1.md
@@ -8,6 +8,12 @@
 * :hammer: 所有 tile 相关的名字 全部改成了 block
 * :hammer: UriModelRegistry 重命名为 UriModelManager
 * :hammer: OptionsFilterRegistry 重命名为 OptionsFilterManager
+* :hammer: HttpStack.ImageHttpResponse 重命名为 HttpStack.Response
+* :hammer: HttpStack.getHttpResponse(String). 重命名为 HttpStack.getResponse(String)
+* :hammer: HttpStack.ImageHttpResponse.getResponseCode() 重命名为 HttpStack.Response.getCode()
+* :hammer: HttpStack.ImageHttpResponse.getResponseMessage() 重命名为 HttpStack.Response.getMessage()
+* :hammer: HttpStack.ImageHttpResponse.getResponseHeadersString() 重命名为 HttpStack.Response.getHeadersString()
+* :hammer: HttpStack.ImageHttpResponse.getResponseHeader() 重命名为 HttpStack.Response.getHeader()
 
 sample app:
 * :bug: 修复 UNSPLASH 页面没有加载完数据就切换到别的页面时崩溃的 BUG

diff --git a/sketch/src/main/java/me/xiaopan/sketch/Configuration.java b/sketch/src/main/java/me/xiaopan/sketch/Configuration.java
@@ -701,7 +701,7 @@ public Configuration setLowQualityImageEnabled(boolean lowQualityImageEnabled) {
     }
 
     /**
-     * 全局解码时优先质量？
+     * 全局解码时优先考虑速度还是质量 (默认优先考虑速度)
      *
      * @return true：质量优先；false：速度优先
      */
@@ -711,9 +711,9 @@ public boolean isInPreferQualityOverSpeedEnabled() {
     }
 
     /**
-     * 设置全局解码时优先考虑质量 (默认优先考虑速度)
+     * 全局解码时优先考虑速度还是质量 (默认优先考虑速度)
      *
-     * @param inPreferQualityOverSpeedEnabled true：质量；false：速度
+     * @param inPreferQualityOverSpeedEnabled true：质量优先；false：速度优先
      * @return {@link Configuration}. 为了支持链式调用
      */
     @NonNull

diff --git a/sketch/src/main/java/me/xiaopan/sketch/Identifier.java b/sketch/src/main/java/me/xiaopan/sketch/Identifier.java
@@ -4,9 +4,9 @@
 
 public interface Identifier {
     /**
-     * 用来生成缓存key，或者在log中标识一个组件
+     * 用来生成缓存 key，或者在 log 中标识一个组件
      * <br>
-     * 通常key是由组件名称和组件属性组成的，例如 String.format("%s(radius=%d,maskColor=%d)", "GaussianBlurImageProcessor", radius, maskColor)
+     * 通常 key 是由组件名称和组件属性组成的，例如 String.format("%s(radius=%d,maskColor=%d)", "GaussianBlurImageProcessor", radius, maskColor)
      */
     @NonNull
     String getKey();

diff --git a/sketch/src/main/java/me/xiaopan/sketch/display/ImageDisplayer.java b/sketch/src/main/java/me/xiaopan/sketch/display/ImageDisplayer.java
@@ -25,6 +25,7 @@
 /**
  * 图片显示器，用来在加载完成后显示图片
  */
+// TODO: 2017/10/30 继续完善 javadoc
 public interface ImageDisplayer extends Identifier {
     int DEFAULT_ANIMATION_DURATION = 400;
 

diff --git a/sketch/src/main/java/me/xiaopan/sketch/http/HttpStack.java b/sketch/src/main/java/me/xiaopan/sketch/http/HttpStack.java
@@ -34,52 +34,60 @@ public interface HttpStack extends Identifier {
     int DEFAULT_MAX_RETRY_COUNT = 0;    // 默认最大重试次数
 
     /**
-     * 获取最大重试次数
+     * 获取最大重试次数，默认值是 {@link HttpStack#DEFAULT_MAX_RETRY_COUNT}
      */
     int getMaxRetryCount();
 
     /**
-     * 设置最大重试次数（默认HttpStack.DEFAULT_MAX_RETRY_COUNT）
+     * 设置最大重试次数
+     *
+     * @param maxRetryCount 最大重试次数
      */
     @SuppressWarnings("unused")
     @NonNull
     HttpStack setMaxRetryCount(int maxRetryCount);
 
     /**
-     * 获取连接超时时间（默认HttpStack.DEFAULT_CONNECT_TIMEOUT）
+     * 获取连接超时时间，单位毫秒，默认值是 {@link HttpStack#DEFAULT_CONNECT_TIMEOUT}
      */
     @SuppressWarnings("unused")
     int getConnectTimeout();
 
     /**
-     * 设置连接超时时间（默认HttpStack.DEFAULT_CONNECT_TIMEOUT）
+     * 设置连接超时时间
+     *
+     * @param connectTimeout 连接超时时间，单位毫秒
      */
     @SuppressWarnings("unused")
     @NonNull
     HttpStack setConnectTimeout(int connectTimeout);
 
     /**
-     * 获取读取超时时间（默认HttpStack.DEFAULT_READ_TIMEOUT）
+     * 获取读取超时时间，单位毫秒，默认值是 {@link HttpStack#DEFAULT_READ_TIMEOUT}
      */
     @SuppressWarnings("unused")
     int getReadTimeout();
 
     /**
-     * 设置读取超时时间（默认HttpStack.DEFAULT_READ_TIMEOUT）
+     * 设置读取超时时间
+     *
+     * @param readTimeout 读取超时时间，单位毫秒
      */
     @SuppressWarnings("unused")
     @NonNull
     HttpStack setReadTimeout(int readTimeout);
 
     /**
-     * 获取User-Agent
+     * 获取自定义请求头中的 User-Agent 属性
      */
     @SuppressWarnings("unused")
     @Nullable
     String getUserAgent();
 
     /**
-     * 设置User-Agent
+     * 设置请求头中的 User-Agent 属性
+     *
+     * @param userAgent 请求头中的 User-Agent 属性
      */
     @SuppressWarnings("unused")
     @NonNull
@@ -93,7 +101,9 @@ public interface HttpStack extends Identifier {
     Map<String, String> getExtraHeaders();
 
     /**
-     * 设置扩展请求属性
+     * 设置扩展请求属性集
+     *
+     * @param extraHeaders 扩展请求属性集
      */
     @SuppressWarnings("unused")
     @NonNull
@@ -108,29 +118,37 @@ public interface HttpStack extends Identifier {
 
     /**
      * 添加可存在多个的请求属性
+     *
+     * @param extraHeaders 扩展请求属性集
      */
     @SuppressWarnings("unused")
     @NonNull
     HttpStack addExtraHeaders(Map<String, String> extraHeaders);
 
     /**
-     * 获取响应
+     * 发送请求并获取响应
+     *
+     * @param uri http uri
+     * @return {@link Response}
      */
     @NonNull
-    ImageHttpResponse getHttpResponse(String uri) throws IOException;
+    Response getResponse(String uri) throws IOException;
 
     /**
      * 是否可以重试
      */
     boolean canRetry(Throwable throwable);
 
-    interface ImageHttpResponse {
+    /**
+     * 统一响应接口
+     */
+    interface Response {
         /**
          * 获取响应状态码
          *
          * @throws IOException IO
          */
-        int getResponseCode() throws IOException;
+        int getCode() throws IOException;
 
         /**
          * 获取响应消息
@@ -139,7 +157,7 @@ interface ImageHttpResponse {
          */
         @SuppressWarnings("unused")
         @Nullable
-        String getResponseMessage() throws IOException;
+        String getMessage() throws IOException;
 
         /**
          * 获取内容长度
@@ -155,13 +173,13 @@ interface ImageHttpResponse {
          * 获取响应头
          */
         @Nullable
-        String getResponseHeader(@NonNull String name);
+        String getHeader(@NonNull String name);
 
         /**
          * 获取所有的响应头
          */
         @Nullable
-        String getResponseHeadersString();
+        String getHeadersString();
 
         /**
          * 获取内容输入流

diff --git a/sketch/src/main/java/me/xiaopan/sketch/http/HurlStack.java b/sketch/src/main/java/me/xiaopan/sketch/http/HurlStack.java
@@ -126,7 +126,7 @@ public String getKey() {
 
     @NonNull
     @Override
-    public ImageHttpResponse getHttpResponse(String uri) throws IOException {
+    public Response getResponse(String uri) throws IOException {
         HttpURLConnection connection = (HttpURLConnection) new URL(uri).openConnection();
 
         connection.setConnectTimeout(connectTimeout);
@@ -165,20 +165,20 @@ protected void processRequest(@SuppressWarnings("UnusedParameters") String uri,
 
     }
 
-    private static class HurlResponse implements ImageHttpResponse {
+    private static class HurlResponse implements Response {
         private HttpURLConnection connection;
 
         HurlResponse(HttpURLConnection connection) {
             this.connection = connection;
         }
 
         @Override
-        public int getResponseCode() throws IOException {
+        public int getCode() throws IOException {
             return connection.getResponseCode();
         }
 
         @Override
-        public String getResponseMessage() throws IOException {
+        public String getMessage() throws IOException {
             return connection.getResponseMessage();
         }
 
@@ -188,7 +188,7 @@ public long getContentLength() {
         }
 
         @Override
-        public String getResponseHeadersString() {
+        public String getHeadersString() {
             Map<String, List<String>> headers = connection.getHeaderFields();
             if (headers == null || headers.size() == 0) {
                 return null;
@@ -247,7 +247,7 @@ public boolean isContentChunked() {
 
         @Nullable
         @Override
-        public String getResponseHeader(@NonNull String name) {
+        public String getHeader(@NonNull String name) {
             return connection.getHeaderField(name);
         }
     }