《Maven官方指南》插件文档标准指南

原文链接     译者:carvendy

介绍

标准从哪里来？

插件文档标准为解决经常抱怨的缺乏文档而编制，特别在Maven插件这块。标准是基于Maven开发邮箱列表的建议而改进。这一个社区maven插件应该怎么样使用的文档共识。

为什么需要一个文档标准

标准不是设置一些条例二十引导插件开发者如何更好地使用插件，为了那些对用户有用的插件来说。标准提醒插件开发者重要的细节需要有文档的，来帮助加快插件推进。

生成文档

推荐你使用maven为了插件来确保生成基础信息，来确保基本信息总是精确和同步的插件实现。 文档生成运行

mvn site

这将会根据pom和src/site中一个插件信息来生成站点，和其他报表插件配置在pom中。最重要的报表插件是Maven Plugin Plugin ，每个插件依赖的mojo注解而生成的文档使用的。但是为了生成站点而可用，这些需要的信息应该被Maven Site Plugin而使用。

POM节点

Maven 从pom提取信息生成数页关于项目的信息。第一步有一个好文档就是精确的和可视化的基本项目信息，Maven可以提供这些给插件只要这些信息在pom中是完整的，可描述的和精确的。

需要的节点

对于一个有效的pom至少需要这些：

  • <modelVersion> – pom模块版本，当前为4.0.0
  • <groupId> 包名
  • <artifactId> 工件名
  • <packaging> 由pom产生工件的类型
  • <version> 插件版本

可选节点

在一个有效的pom中这些是可选的节点，但是对于项目基本信息很重要的，用户有效地使用插件的时候需要。

  • <name> – 插件名字，Maven NNN Plugin 作为Maven项目名字或者NNN Maven Plugin来 命名。
  • <description> – 项目描述，一个插件可以做什么的概述
  • <url> – 网站插件,通常是maven.apache.org 或 org.mojohaus
  • <prerequisites> – 使用这个插件需要的最小版本号
  • <issueManagement> – 描述系统使用过程一些问题报表和修改需求
[...]
  <issueManagement>
    <system>jira</system>
    <url>http://jira.someproject.org</url>
  </issueManagement>    
  [...]
  • <inceptionYear> 哪一年被创建的
  • <mailingLists> 列表上是一些可以联系的使用者或开发者，可以提供帮助或者讨论
[...]
  <mailingLists>
    <mailingList>
      <name>Project users</name>
      <post>announce@noonecares.com</post>
      <subscribe>users-subscribe@noonecares.com</subscribe>
      <unsubscribe>users-unsubscribe@noonecares.com</unsubscribe>
      <archive>http://noonecares.archive.org</archive>
    </mailingList>    
    <mailingList>
      [...]
    </mailingList>
  </mailingLists>    
  [...]
  • <licenses> 插件协议
[...]
  <licenses>
    <license>
      <name>Apache License, Version 2.0</name>
      <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
      <distribution>repo</distribution>
    </license>
  </licenses>
  [...]
  • <scm> 源代码管理配置-没有这个插件会引起怀疑，可能不是OSS
[...]
  <scm>
    <connection>scm:svn:http://noonecares.com/some/plugin/project/trunk</connection>
    <developerConnection>scm:svn:https://noonecares.com/some/plugin/project/trunk</developerConnection>
    <url>http://noonecares.com/viewvc/some/project/trunk/</url>
  </scm>
  [...]
  • <organization> 该组织维护插件，以防万一我们需要有人责怪

插件配置参数

Maven Plugin Plugin 的责任是生成插件站点信息和需要加入 <reporting> 部分除非已经继承了父级的pom：

[...]
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-plugin-plugin</artifactId>
        <version>2.5.1</version>
      </plugin>
    </plugins>
  </reporting>    
  [...]

注释，注解和插件参数的命名是从插件源码中提取的和提供给插件信息页。为了可以生成站点是有用的，这里有一些指南你可以跟着做当你记录插件的时候。

  • all @parameter 字段应该有一个描述的注释，见闻足以让一个普通用户理解
[...]
/**
 * Put something informative here that a regular user can understand.
 * 
 * @parameter 
 */
private boolean someparameter;
[...]
  • 类级别的注释应该解释指令是做什么的
[...]
/**
 * Everything here will show up on the top of the generated plugin info page.
 *
 * @goal somegoal
 * @phase compile
 */
public class ExampleMojo
    extends AbstractWarMojo
{
    public void execute()
        throws MojoExecutionException, MojoFailureException
    {  
[...]
  • @component 和 @readonly 参数不需要任何注释但是依然是一个很好的例子提供。

站点组织

可见的信息也是很关键的，有一致的航行线将很大提高这些可见的文档。索引页可以帮助强调重要的部分和文档的所有页。

站点描述符

站点描述符描述航线和可以在src/site/site.xml找到。下面就是建议的站点描述符模板：

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <body>
    <menu name="Overview">
      <item name="Introduction" href="index.html"/>
      <item name="Goals" href="plugin-info.html"/>
      <item name="Usage" href="usage.html"/>
      <item name="FAQ" href="faq.html"/>
    </menu>
   
    <menu name="Examples">
      <item name="description1" href="examples/example-one.html"/>
      <item name="description2" href="examples/example-two.html"/>
    </menu>
  </body>
</project>

航线

  • 介绍 介绍在插件文档的前面部分。这对于任何部分来是个好地方和在页面是需要被强调的。这可以建把议生成插件的参数配置链接到这。下面是建议的src/site/apt/index.apt模板
------
 Introduction
 ------
 Author
 ------
 YYYY-MM-DD
 ------
 
 
Plugin Name
 
  Plugin introduction, description, and other relevant information.
 
* Goals Overview
 
  General information about the goals.
 
  * {{{<goal>.html}prefix:goal}} short description for this plugin goal.
 
* Usage
 
  General instructions on how to use the Plugin Name can be found on the {{{usage.html}usage page}}. Some more
  specific use cases are described in the examples given below. Last but not least, users occasionally contribute
  additional examples, tips or errata to the
  {{{http://docs.codehaus.org/display/MAVENUSER/Plugin+Name}plugin's wiki page}}.
 
  In case you still have questions regarding the plugin's usage, please have a look at the {{{faq.html}FAQ}} and feel
  free to contact the {{{mail-lists.html}user mailing list}}. The posts to the mailing list are archived and could
  already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching
  the {{{mail-lists.html}mail archive}}.
 
  If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our
  {{{issue-tracking.html}issue tracker}}. When creating a new issue, please provide a comprehensive description of your
  concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason,
  entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated.
  Of course, patches are welcome, too. Contributors can check out the project from our
  {{{source-repository.html}source repository}} and will find supplementary information in the
  {{{http://maven.apache.org/guides/development/guide-helping.html}guide to helping with Maven}}. 
 
* Examples
 
  To provide you with better understanding of some usages of the Plugin Name,
  you can take a look into the following examples:
 
  * {{{examples/example-one.html}Example Description One}}
 
  * {{{examples/example-two.html}Example Description Two}}
  • 指令 plugin-info.html 是被Maven Plugin Plugin创建的。直到Maven Site Plugin被更新它将更好推向更好可视化的主菜单。这包含指令和他们描述和链接到配置参数。信息是基于插件的注释和注解。
  • 使用（这是以前所谓的怎么做） 使用页描述了插件目标的基本用例，包括示例POM配置和如何解释目标的工作。
  • FAQ 一个好的文档项目总是整理一些频繁抛出的问题，并总是放置src/site/fml/faq.fml。这个例子提供一个模板给你的FAQ:
<?xml version="1.0" encoding="UTF-8"?>
<faqs id="FAQ" title="Frequently Asked Questions">
  <part id="General">
    <faq id="question">
      <question>Question?</question>
      <answer>
        <p>
          Answer
        </p>
      </answer>
    </faq>
  </part>
</faqs>
  • 例子 位于使用页中的高级配置和示例位于此处。高级用户希望最大限度地使用插件可以检查这里的项目。如何有效地使用插件的提示也是一个很好的东西放在这里。 在“示例”项下的示例检查这些插件站点：

推荐配置报告

有2个推荐报告插件增强插件文件，javadoc JXR。

  • Maven Javadoc Plugin javadocs提供的文件，使得它更容易为开发人员知道如何使用一个特定的类。而不是阅读和理解实际的源代码，开发者可以使用javadocs来查找类的属性和方法。 可用的javadoc为了你的插件加上这些在你pom.xml
[...]
  <build>
    [...]
  </build>
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>2.4</version>
        <configuration>
          <minmemory>128m</minmemory>
          <maxmemory>512</maxmemory>
          ...
        </configuration>
      </plugin>
    </plugins>
    [...]
  </reporting>   
  [...]

检查文档要使用插件的 javadoc:javadoc 为了更优的配置。

  • Maven JXR Plugin Maven JXR Plugin 生成一个项目源码的交叉引用。生成的交叉引用被链接到对应的javadoc文件如果javadoc被创建了。这个交叉引用对于那些想更好理解插件内部工作是有显著成效的。

要启用源代码交叉引用，请将下列内容添加到你的pom.xml

[...]
  <build>
    [...]
  </build>
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jxr-plugin</artifactId>
        <version>2.1</version>
      </plugin>
    </plugins>
  </reporting>    
  [...]

检查JXR配置页为了可能的配置参数。

原创文章，转载请注明： 转载自并发编程网 – ifeve.com本文链接地址: 《Maven官方指南》插件文档标准指南

  • Trackback 关闭
  • 评论 (0)

  1. 暂无评论

return top