complete docs

webmagic-extension/src/main/java/us/codecraft/webmagic/model/ModelPipeline.java

@@ -11,7 +11,8 @@ import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
 
 /**
- * 基于Pipeline的扩展点。<br>
+ * 基于Pipeline的扩展点，用于实现注解格式的Pipeline。<br>
+ * 与PageModelPipeline是一对多的关系(原谅作者没有更好的名字了)。<br>
  * @author code4crafter@gmail.com <br>
  * @date: 13-8-2 <br>
  * Time: 上午10:47 <br>

webmagic-extension/src/main/java/us/codecraft/webmagic/model/annotation/ExtractBy.java

@@ -6,22 +6,45 @@ import java.lang.annotation.Target;
 
 /**
  * 定义类或者字段的抽取规则。<br>
+ *
  * @author code4crafter@gmail.com <br>
  * @date: 13-8-1 <br>
  * Time: 下午8:40 <br>
  */
 @Retention(java.lang.annotation.RetentionPolicy.RUNTIME)
-@Target({ElementType.FIELD,ElementType.TYPE})
+@Target({ElementType.FIELD, ElementType.TYPE})
 public @interface ExtractBy {
 
+    /**
+     * 抽取规则
+     *
+     * @return 抽取规则
+     */
     String value();
 
     public enum Type {XPath, Regex, Css}
 
+    /**
+     * 抽取规则类型，支持XPath、Css selector、正则表达式，默认是XPath
+     *
+     * @return 抽取规则类型
+     */
     Type type() default Type.XPath;
 
+    /**
+     * 是否是不能为空的关键字段，若notNull为true，则对应字段抽取不到时，丢弃整个类，默认为false
+     *
+     * @return 是否是不能为空的关键字段
+     */
     boolean notNull() default false;
 
+    /**
+     * 是否抽取多个结果<br>
+     * 用于字段时，需要List<String>来盛放结果<br>
+     * 用于类时，表示单页抽取多个对象<br>
+     *
+     * @return 是否抽取多个结果
+     */
     boolean multi() default false;
 
 }

webmagic-extension/src/main/java/us/codecraft/webmagic/model/annotation/ExtractBy2.java

@@ -5,7 +5,7 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 /**
- * 定义类或者字段的抽取规则。<br>
+ * 定义类或者字段的抽取规则，只能在Extract、ExtractByRaw之后使用。<br>
  *
  * @author code4crafter@gmail.com <br>
  * @date: 13-8-1 <br>

webmagic-extension/src/main/java/us/codecraft/webmagic/model/annotation/ExtractBy3.java

@@ -5,7 +5,7 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 /**
- * 定义类或者字段的抽取规则。<br>
+ * 定义类或者字段的抽取规则，只能在Extract、ExtractByRaw之后使用。<br>
  * @author code4crafter@gmail.com <br>
  * @date: 13-8-1 <br>
  * Time: 下午8:40 <br>

webmagic-extension/src/main/java/us/codecraft/webmagic/model/annotation/ExtractByRaw.java

@@ -6,22 +6,44 @@ import java.lang.annotation.Target;
 
 /**
  * 对于在Class级别就使用过ExtractBy的类，在字段中想抽取全部内容可使用此方法。<br>
+ *
  * @author code4crafter@gmail.com <br>
  * @date: 13-8-1 <br>
  * Time: 下午8:40 <br>
  */
 @Retention(java.lang.annotation.RetentionPolicy.RUNTIME)
-@Target({ElementType.FIELD,ElementType.TYPE})
+@Target({ElementType.FIELD, ElementType.TYPE})
 public @interface ExtractByRaw {
 
+    /**
+     * 抽取规则
+     *
+     * @return 抽取规则
+     */
     String value();
 
     public enum Type {XPath, Regex, Css}
 
+    /**
+     * 抽取规则类型，支持XPath、Css selector、正则表达式，默认是XPath
+     *
+     * @return 抽取规则类型
+     */
     Type type() default Type.XPath;
 
+    /**
+     * 是否是不能为空的关键字段，若notNull为true，则对应字段抽取不到时，丢弃整个类，默认为false
+     *
+     * @return 是否是不能为空的关键字段
+     */
     boolean notNull() default false;
 
+    /**
+     * 是否抽取多个结果<br>
+     * 需要List<String>来盛放结果<br>
+     *
+     * @return 是否抽取多个结果
+     */
     boolean multi() default false;
 
 }

webmagic-extension/src/main/java/us/codecraft/webmagic/model/annotation/ExtractByUrl.java

@@ -14,10 +14,27 @@ import java.lang.annotation.Target;
 @Target({ElementType.FIELD})
 public @interface ExtractByUrl{
 
+    /**
+     * 抽取规则，支持正则表达式
+     *
+     * @return 抽取规则
+     */
     String value() default "";
 
+    /**
+     * 是否是不能为空的关键字段，若notNull为true，则对应字段抽取不到时，丢弃整个类，默认为false
+     *
+     * @return 是否是不能为空的关键字段
+     */
     boolean notNull() default false;
 
+    /**
+     * 是否抽取多个结果<br>
+     * 用于字段时，需要List<String>来盛放结果<br>
+     * 用于类时，表示单页抽取多个对象<br>
+     *
+     * @return 是否抽取多个结果
+     */
     boolean multi() default false;
 
 }

webmagic-extension/src/main/java/us/codecraft/webmagic/model/annotation/HelpUrl.java

@@ -14,7 +14,17 @@ import java.lang.annotation.Target;
 @Target({ElementType.TYPE})
 public @interface HelpUrl {
 
+    /**
+     * 某个类对应的URL规则列表<br>
+     * webmagic对正则表达式进行了修改，"."仅表示字符"."而不代表任意字符，而"\*"则代表了".\*"，例如"http://\*.oschina.net/\*"代表了oschina所有的二级域名下的URL。<br>
+     *
+     * @return 抽取规则
+     */
     String[] value();
 
+    /**
+     * 指定提取URL的区域(仅支持XPath)
+     * @return 指定提取URL的区域
+     */
     String sourceRegion() default "";
 }

webmagic-extension/src/main/java/us/codecraft/webmagic/model/annotation/TargetUrl.java

@@ -6,6 +6,7 @@ import java.lang.annotation.Target;
 
 /**
  * 定义某个类抽取的范围和来源，sourceRegion可以用xpath语法限定抽取区域。<br>
+ *
  * @author code4crafter@gmail.com <br>
  * @date: 13-8-1 <br>
  * Time: 下午8:40 <br>
@@ -14,8 +15,18 @@ import java.lang.annotation.Target;
 @Target({ElementType.TYPE})
 public @interface TargetUrl {
 
+    /**
+     * 某个类对应的URL规则列表<br>
+     * webmagic对正则表达式进行了修改，"."仅表示字符"."而不代表任意字符，而"\*"则代表了".\*"，例如"http://\*.oschina.net/\*"代表了oschina所有的二级域名下的URL。<br>
+     *
+     * @return 抽取规则
+     */
     String[] value();
 
+    /**
+     * 指定提取URL的区域(仅支持XPath)
+     * @return 指定提取URL的区域
+     */
     String sourceRegion() default "";
 
 }

webmagic-extension/src/main/java/us/codecraft/webmagic/pipeline/JsonFilePipeline.java

@@ -12,7 +12,7 @@ import java.io.IOException;
 import java.io.PrintWriter;
 
 /**
- * 持久化到文件的接口。
+ * JSON格式持久化到文件的接口。
  *
  * @author code4crafter@gmail.com <br>
  *         Date: 13-4-21

webmagic-extension/src/main/java/us/codecraft/webmagic/pipeline/PagedPipeline.java

@@ -9,6 +9,9 @@ import java.util.*;
 import java.util.concurrent.ConcurrentHashMap;
 
 /**
+ * 用于实现分页的Pipeline。<br>
+ * 在使用redis做分布式爬虫时，请不要使用此功能。<br>
+ *
  * @author code4crafter@gmail.com <br>
  * @date: 13-8-4 <br>
  * Time: 下午5:15 <br>
@@ -34,7 +37,7 @@ public class PagedPipeline implements Pipeline {
         if (o instanceof PagedModel) {
             PagedModel pagedModel = (PagedModel) o;
             pageMap.put(pagedModel.getPageKey(), pagedModel.getPage(), Boolean.TRUE);
-            if (pagedModel.getOtherPages()!=null){
+            if (pagedModel.getOtherPages() != null) {
                 for (String otherPage : pagedModel.getOtherPages()) {
                     Boolean aBoolean = pageMap.get(pagedModel.getPageKey(), otherPage);
                     if (aBoolean == null) {
@@ -70,8 +73,8 @@ public class PagedPipeline implements Pipeline {
                     }
                 });
                 PagedModel value = entryList.get(0).getValue();
-                for (int i=1;i<entryList.size();i++){
-                    value=value.combine(entryList.get(i).getValue());
+                for (int i = 1; i < entryList.size(); i++) {
+                    value = value.combine(entryList.get(i).getValue());
                 }
                 objectEntry.setValue(value);
             }