精华内容
下载资源
问答
  • 2020-09-19 21:05:32

    工匠若水可能会迟到,但是从来不会缺席,最终还是觉得将自己的云笔记分享出来吧 ~

    缘由

    相信大家都用过 javadoc 命令或者 IDE 封装命令生成 java api doc 文档吧,但是你有没有反思过 javadoc 命令是怎么解析文件生成的呢?其实 javadoc 在 jdk 目录下只是一个可执行程序,但是这个可执行程序是基于 jdk 的 tools.jar 的一个封装,也就是说 javadoc 实现在 tools.jar 中。

    很多时候我们可能会有一些奇葩的需求,譬如获取 java 文档注释进行搞事情处理,我们该怎样解析 java 文件去获取这些注释信息呢?你可能一开始想过使用正则匹配,但是这个方案其实是有兼容性问题的。或者说,你考虑过使用一些第三方库来解析 java 源码文件,但是这些库很多都是针对 java 源码的,而非源码中的注释。所以有一个超级棒的方案就是自定义 doclet,采用 javadoc 操作。

    方案验证

    既然说到这个方案依赖 javadoc 和 doclet,那就先去看看这方面的文档进行一下技术评估,具体参见 oracle 官方文档:

    通过文档我们可以发现,其实我们只用自定义一个 Doclet 类就行了,至于怎么定义其实文档中已经写的很详细了,还给出了具体代码片段,我们可以直接搬过来进行验证即可,代码如下:

    public class CustomerDoclet extends Doclet {
      public static boolean start(RootDoc root) {
        ClassDoc[] classes = root.classes();
        //注释文档信息,自己爱怎么解析组织就怎么解析了,看自己需求
        return true;
      }public static void main(String[] args) {
         String[] docArgs =
             new String[] {
               "-doclet", CustomerDoclet.class.getName(), "/home/yan/test/cn/test/JavaSource.java"
             };
         com.sun.tools.javadoc.Main.execute(docArgs);
      }
    

    简单吧,运行上面代码段就能自定义 javadoc 输出解析了。跑了下发现没问题,那就开始搞事情吧。

    实现一个 gradle 插件进行 javadoc 自定义操作

    这里我们为了简单和直接说明核心,所以打算实现一个检查 android、androidLibrary、java、javaLibrary 代码源文件中是否包含 javadoc @author 的插件,插件名称 gradle-javadoc-checker,具体完整插件源码可以访问https://github.com/yanbober/gradle-javadoc-checker获取。

    注意:这部分内容需要你先对 gradle 插件开发比较熟悉才能看懂,所以建议先掌握所说的知识后进行研读。

    添加依赖

    dependencies {
        compile gradleApi()
        compile 'com.android.tools.build:gradle:3.1.0'
        //tools.jar 的依赖
        compile files(org.gradle.internal.jvm.Jvm.current().toolsJar)
    }
    

    编写自定义 javadoc 判断 @author 工具

    public class JavaDocReader {
        private static RootDoc root;
    	//自定义 doclet
        public static class CustomerDoclet {
            public static boolean start(RootDoc root) {
                JavaDocReader.root = root;
                return true;
            }
        }
    
        //tools.jar 中 javadoc 的封装
        public static RootDoc process(String[] extraArges) {
            List<String> argsOrderList = new ArrayList<>();
            argsOrderList.add("-doclet");
            argsOrderList.add(CustomerDoclet.class.getName());
            argsOrderList.addAll(Arrays.asList(extraArges));
            String[] args = argsOrderList.toArray(new String[argsOrderList.size()]);
            System.out.println(args);
            Main.execute(args);
            return root;
        }
    
        //tools.jar 中 javadoc 的封装
        public static void process(List<String> sourcePaths, List<String> javapackages,
                                   List<String> excludePackages, String outputDir) throws Exception {
            String paths = list2formatString(sourcePaths, ";");
            String includes = list2formatString(javapackages, ":");
            String excludes = list2formatString(excludePackages, ":");
    
            List<String> argsOrderList = new ArrayList<>();
            argsOrderList.add("-doclet");
            argsOrderList.add(CustomerDoclet.class.getName());
    
            if (paths != null && paths.length() > 0) {
                argsOrderList.add("-sourcepath");
                argsOrderList.add(paths);
            }
    
            argsOrderList.add("-encoding");
            argsOrderList.add("utf-8");
            argsOrderList.add("-verbose");
    
            if (includes != null && includes.length() > 0) {
                argsOrderList.add("-subpackages");
                argsOrderList.add(includes);
            }
    
            if (excludes != null && excludes.length() > 0) {
                argsOrderList.add("-exclude");
                argsOrderList.add(excludes);
            }
    
            String[] args = argsOrderList.toArray(new String[argsOrderList.size()]);
            System.out.println(Arrays.toString(args));
    		//执行 tools.jar 中的 javadoc 命令
            Main.execute(args);
    
            File file = new File(outputDir);
            if (!file.exists()) {
                file.mkdirs();
            }
            file = new File(file, new Date().toString() + ".txt");
            FileOutputStream outputStream = new FileOutputStream(file);
    		//判断每个顶级 java class 是否有编写 @author 人,没有就筛出来写入一个文件记录
            ClassDoc[] classes = root.classes();
            if (classes != null) {
                for (int i = 0; i < classes.length; ++i) {
                    if (classes[i].containingClass() == null && classes[i].isPublic()) {
                        Tag[] authorTags = classes[i].tags("author");
                        if (authorTags == null || authorTags.length == 0) {
                            String filename = classes[i].position().file().getAbsolutePath();
                            outputStream.write((filename+"\r\n").getBytes());
                        }
                    }
                }
            }
            root = null;
            outputStream.flush();
            outputStream.close();
        }
    
        private static String list2formatString(List<String> srcs, String div) {
            StringBuilder stringBuilder = new StringBuilder();
            for (int index=0; index<srcs.size(); index++) {
                if (index > 0) {
                    stringBuilder.append(div);
                }
                stringBuilder.append(srcs.get(index));
            }
            return stringBuilder.toString();
        }
    }
    

    有了 javadoc 自定义工具类,接下来编写 gradle 自定义 task 即可。

    编写自定义 gradle task 进行检查

    //groovy 编写
    class JavaDocCheckerTask extends DefaultTask {
        //自定义 task 的输入
        @Input
        List<String> includePackages
    
        @Input
        List<String> excludePackages
    
        @Input
        List<String> sourcePaths
    
        //自定义 task 的输出
        @OutputDirectory
        String outputDir
    
        //自定义 task 的执行逻辑
        @TaskAction
        void checker() {
            if (sourcePaths == null || sourcePaths.size() == 0) {
                throw new GradleScriptException("JavaDocCheckerTask sourcePaths params can't be null or empty!")
            }
    
            if (outputDir == null || outputDir.length() == 0) {
                throw new GradleScriptException("JavaDocCheckerTask outputDir params can't be null or empty!")
            }
    		//task 依据输出输出参数进行 javadoc 命令操作
            JavaDocReader.process(sourcePaths, includePackages, excludePackages, outputDir)
        }
    }
    

    有了自定义 gradle task 进行 javadoc 操作,接下来就该接入插件了。

    将自定义 task 加入构建 project

    先定义插件的 extension 拓展参数:

    class CheckerExtension {
        public static final String NAME = "javadocChecker"
    
        List<String> includePackages
    
        List<String> excludePackages
    
        List<String> sourcePaths
    
        String outputDirectory
    }
    

    将拓展参数与 task 结合:

    class JavaDocCheckerPlugin implements Plugin<Project> {
        @Override
        void apply(Project project) {
            //插件添加自定义 extension
            project.extensions.create(CheckerExtension.NAME, CheckerExtension)
            //将自定义任务加入 project
            project.tasks.create("javaDocChecker", JavaDocCheckerTask)
    
            //依据 apply 的是 java、androidlibrary、androidapplication 分别获取对应的拓展参数
            JavaPluginConvention java = null
            BaseExtension android = null
            if (project.plugins.hasPlugin(AppPlugin)) {
                android = project.extensions.getByType(AppExtension)
            } else if(project.plugins.hasPlugin(LibraryPlugin)) {
                android = project.extensions.getByType(LibraryExtension)
            } else if (project.plugins.hasPlugin(JavaPlugin)) {
                java = project.convention.getPlugin(JavaPluginConvention)
            }
    
            if (java == null && android == null) {
                throw new GradleException("it's a not support plugin type!")
            }
    
            project.afterEvaluate {
                afterEvaluateInner(project, java, android)
            }
        }
    
        private void afterEvaluateInner(Project project, JavaPluginConvention java, BaseExtension android) {
            if (java != null) {
                //java 插件就进行 java 的 sourceSets 处理
                processJava(project, java)
            } else if (android != null) {
                //Android 插件就进行 android 的 sourceSets 处理
                processAndroid(project, android)
            }
        }
    
        private void processJava(Project project, JavaPluginConvention java) {
            List<String> sources = new ArrayList<>()
            //拿到 java sourceSets main 的 src 进行检查处理
            SourceSet mainSourceSet = java.sourceSets.getByName(SourceSet.MAIN_SOURCE_SET_NAME)
            mainSourceSet.allJava.srcDirs.each {
                sources.add(it.absolutePath)
            }
    
            assignedTask(project, sources)
        }
    
        private void processAndroid(Project project, BaseExtension android) {
            List<String> sources = new ArrayList<>()
            //拿到 android sourceSets main 的 src 进行检查处理
            AndroidSourceSet mainSourceSet = android.sourceSets.getByName(SourceSet.MAIN_SOURCE_SET_NAME)
            mainSourceSet.java.srcDirs.each {
                sources.add(it.absolutePath)
            }
    
            assignedTask(project, sources)
        }
    
        //把插件 extension 的自定义属性赋值给自定义 task 的 input 和 output
        private void assignedTask(Project project, List<String> sources) {
            def checker = project[CheckerExtension.NAME]
            if (checker == null) {
                return
            }
    
            project.getTasksByName("javaDocChecker", false).each {
                it.configure {
                    includePackages = checker.includePackages == null ? [] : checker.includePackages
                    excludePackages = checker.excludePackages == null ? [] : checker.excludePackages
                    sourcePaths = sources
                    outputDir = checker.outputDirectory
                }
            }
        }
    }
    

    到此插件核心主体就开发完了,然后就可以使用了,这就是一个完整的通过自定义 javadoc 输出来解决实际问题的小项目,感兴趣可以访问项目源码进行研究,也可以自定义自己的操作。具体完整插件源码可以访问 https://github.com/yanbober/gradle-javadoc-checker 获取。

    总结

    本文给出了一个实现思路,你可以发现,doclet 简直就是一个巨无霸,对于 java doc 文档操作只有你想不到的,没有他做不到的。希望对你有所启发。

    在这里插入图片描述

    【工匠若水 未经允许严禁转载,请尊重作者劳动成果。+微信 yanbo373131686 联系我】

    更多相关内容
  • Javadoc 注释自定义

    2019-12-25 19:56:55
    template text ,一模一样拷贝,前面不要加什么/** * * * * @author abcwangjingjing * @date $date$ $time$ * @param $params$ * @return $returns$ ...groovyScript("if(\"${_1}\".len...

    template  text ,一模一样拷贝,前面不要加什么/**

    *
     *
     *
     * @author abcwangjingjing
     * @date $date$ $time$
     * @param $params$
     * @return $returns$
     **/

    edit variables:


    params:

    groovyScript("if(\"${_1}\".length() == 2) {return '';} else {def result=''; def params=\"${_1}\".replaceAll('[\\\\[|\\\\]|\\\\s]', '').split(',').toList();for(i = 0; i < params.size(); i++)  {if(i==0){result+= params[i] + ': '}else{result+='\\n' + ' * @param ' + params[i] + ': '}}; return result;}", methodParameters()); 

    returns:

    groovyScript("def returnType = \"${_1}\"; def result = returnType; return result;", methodReturnType()); 

     

    展开全文
  • 主要介绍了详解IDEA自定义注释模板(javadoc),小编觉得挺不错的,现在分享给大家,也给大家做个参考。一起跟随小编过来看看吧
  • 针对于有需要控制JavaDoc生成内容的需求...对于使用了自定义注解的类才生成JavaDoc。且支持类和方法两个粒度。在类上使用就生成整个类的,在方法上生成就生成单个方法的。配合gradle task使用,具体代码可见本人博客。
  • 使用IDEA生成JavaDoc文档+自定义注解模板一、注释标签介绍二、IDEA生成JavaDoc文档2.1、IDEA选择`Tools`->`Generate JavaDoc`2.2、注意以下三个地方2.3、注意三、自定义注解模板3.1、注解在类上3.1.1图内模板3.2...

    一、注释标签介绍

    标记说明标签类型
    @author作者标识包、类、接口
    @version版本号包、类、接口
    @param方法的入参名及描述信息,如入参有特别要求,可在此注释构造函数、方法
    @return对函数返回值的注释方法
    @deprecated标识随着程序版本的提升,当前API已经过期,仅为了保证兼容性依然存在.以此告之开发者不应再用这个API包、类、接口、值域、构造函数、方法
    @throws构造函数或方法所会抛出的异常构造函数、方法
    @exception同@throws构造函数、方法
    @see查看相关内容,如类,方法,变量等包、类、接口、值域、构造函数、方法
    @sinceAPI在什么程序的什么版本后开发支持包、类、接口、值域、构造函数、方法
    @link链接到某个特定的成员对应的文档中包、类、接口、值域、构造函数、方法
    @value当对常量进行注释时,如果想将其值包含在文档中,则通过该标签来引用常量的值静态值域

    此外还有@serial、@serialField、@serialData、{@docRoot)、{@inheritDoc)、{@lteral})、{@code} {@value arg}几个不常用的

    二、IDEA生成JavaDoc文档

    2.1、IDEA选择Tools->Generate JavaDoc

    在这里插入图片描述

    2.2、注意以下三个地方

    1. 第一个是设置输入的地址

    最好先弄一个空文件夹,再把地址定到那里,这个JavaDoc文件是一堆文件的,得放一个空文件夹好查看

    1. 第二个是设置语言

    zh_CN

    1. 第三个是设置字符集编码

    -encoding utf-8 -charset utf-8

    在这里插入图片描述

    2.3、注意

    以上注释标签里在模板里一定要写规范,否则生成JavaDoc文档时会报错,比如把@author写成@Author

    三、自定义注解模板

    3.1、注解在类上

    在这里插入图片描述

    3.1.1图内模板
    /** 
     * 
     * @author ${USER}
     * @date ${DATE} ${TIME}
     * @version 1.0
     */
    

    3.2、注解在方法上

    在这里插入图片描述
    在这里插入图片描述

    3.2.1、params里的脚本代码

    groovyScript(“def result=’’; def params=”${_1}".replaceAll(’[\\[|\\]|\\s]’, ‘’).split(’,’).toList(); for(i = 0; i < params.size(); i++) {if(params[i] == ‘’) continue;if(i==0) result += params[0]+((params.size()==1)?’’:’\n’);else{ result+=’ * @param ’ + params[i] + ((i < params.size() - 1) ? ‘\n’ : ‘’)}}; return result", methodParameters())

    3.2.2、图内模板
    *
     *
     * @param $params$
     * @return $return$
     * @author DengHongWei
     * @date $date$ $time$
     */
    
    展开全文
  • javadoc自定义

    2013-07-06 15:31:37
    javadoc自定义
  • 项目中对于注释和代码规范的要求往往是毕比较严格的,如果全靠手动完成效率低,还难以保证保证的规范。幸好Eclipse给我们提供了...,恩,这是我自定义过的注释模版。效果是在给方法用/**注释内容*/,注释的时候,会生成

    项目中对于注释和代码规范的要求往往是毕比较严格的,如果全靠手动完成效率低,还难以保证保证的规范。幸好Eclipse给我们提供了自定义代码模版的功能。

     
    先说一下Java代码注释模版,它是指这里的配置:
     
     

     
    是不是跟你的不一样,多了@author和@date ?,恩,这是我自定义过的注释模版。效果是在给方法用/**注释内容*/,注释的时候,会生成如下形式的代码:
     

     
    ${tags}是生成@param,@return这些结果。其余的应该不用我多说了。
     
    定义这样的模版很简单,在刚才的位置,点Edit,按照如下的输入即可:
     
     
    这就够了?当然不是,如果在之前的方法忘记了@date时间注释,要怎么补上?直接用@ + 代码辅助?是不是找不到@date 标签?呵呵,当然,这个@date其实是我自定义的。定义的位置在这里:
     

     
    赶紧New一个 @date标签吧。
     
     
    注:Pattern中 @date字符为手动填写。后面两个变量为Eclipse内部提供的。
     
    保存看看效果?
     
     
    @date 出现了吧。

    本文出自 “ 苦逼coder ” 博客
    展开全文
  • JavaDoc注释自定义(针对eclipse,没有尝试过myeclipse,idea) 自定义方法注释的模板注释如下: 模板来自菜鸟联盟 /** * @Title:${enclosing_method} * @Description: [功能描述] * @Param: ${tags} *...
  • javadoc 生成自定义的标签

    千次阅读 2015-05-19 14:53:41
    http://www.blogjava.net/lishunli/archive/2010/01/12/309218.html Technorati 标记: tools 关键词 个性化地生成Javadoc文档,svn eclipse 设置属性 svn:keywords -TortoiseSVN,李顺利, Javadoc 自定义标记,...
  • javadoc注释

    2021-10-26 14:30:35
    javadoc.exe生成帮助文档 Java零基础教程视频(适合Java 0基础,Java初学入门)_哔哩哔哩_bilibiliP19
  • 在gradle中定义了一个自定义的task,该task用于生成JavaDoc task generatePublicAPIDocs(type: JavaDoc){ List<File> list = new ArrayList() list.add(file("src/main/java/com/fr/doclet")) options...
  • JavaDoc生成文档(文档注释) 参数信息: @author 作者名 @version 版本号 @since 指明需要最早使用的jdk版本 @param 参数名 @return 返回值情况 @throws 异常抛出情况 可以在...
  • 实现javadoc自定义输出——doclet

    千次阅读 2016-12-24 17:40:24
    doclet可以代替javadoc的输出,借由javadoc可以获取源码几乎所有的信息,类名、类变量、类方法、方法参数、注解javadoc注释等都可以获取到,然后根据自己的需要把关心的信息输出成自定的格式。
  • (一)通常javadoc模版注释产生方法:在函数名上面一行输入/**,自动会生成如下注释格式:/***这里可以简单介绍函数功能*@param*@param*@return*/(二)生成javadoc:点击android studio菜单栏Tools->Generate ...
  • JAVA注释详解及个性化生成javadoc文档 一、注释详解 注释主要就是对程序的解释说明 单行注释(// 注释文字) 多行注释(/* 注释文字 */) 文档注释(/** 注释文档 */)JAVA特有 文档注释通过 Javadoc 生成相应的 ...
  • Maven插件,用于从JAX-RS和Javadoc注释生成Swagger 这个Maven插件正在为基于JAX-RS的Java服务器生成Swagger API文档。 JAX-RS批注中未包含的其他信息放置在Javadoc注释中。 例 此处提供了一个使用javadoc2swagger-...
  • easy-javadoc-1.12.jar

    2020-08-26 15:30:56
    可以在intellij idea 中自动生成注释文档 可以在intellij idea 2018-2019都可使用
  • java注释自定义

    2021-02-27 20:23:31
    展开全部它类似于新创建一个接口类文件,但为了区分,我们需要将它声明为@...public@interfaceNewAnnotation {}使用自定义注解32313133353236313431303231363533e58685e5aeb931333361303036类型Java代码package...
  • 07-07JavaDoc文档注释

    2021-07-07 21:09:39
    JavaDoc文档注释 /** * @author Chenyan * @version 1.0 * @since 1.8 */ public class Doc { //属性 String name; /** * @author Chenyan * @param name * @return * @throws Exception */ //方法 ...
  • idea结合javadoc注释

    千次阅读 2018-06-19 17:02:22
    Editor–&...class、Interface、Enum均添加如下注释 /** * ${PROJECT_NAME} * ${DATE} ${TIME} * ${description} * * * @author lanhaifeng * @since **/ Editor–&gt;Live Templates创建...
  • 自定义注释:  1、File->Setting->Editor->Live Templates,创建Template Group,命名为myTemplate。  2、在myTemplate下创建Live Templates,创建cdoc(类注释)和m(方法注释)注释模板。下图为自己项目中常...
  • 解决阿里代码规范检测中方法缺少javadoc注释的问题 一、问题描述 安装了阿里代码检测的插件后,敲一个简单的方法,发现提示有问题,如下 /** * 查找User的集合 */ List<User> findAll(); 提示信息为: ...
  • 一、注解的概念及作用1.什么是注解源代码中元数据的一种标记,注解本质上是一个继承自Annotation的类(一般通过反射的方式实现具体的功能)2.注解的作用生成文档,根据文档注解,可以生成java文档追踪代码依赖性,实现...
  • 代码形象——javadoc注释规范

    万次阅读 多人点赞 2017-03-25 14:19:43
    javadoc注释规范 备注:本文结合了许多篇文章的内容加上自己的理解和经验,将很多零散的知识点,总结和统一整理与此。 你必须写注释而且按照项目规范来的写注释的理由 javadoc注释规范就是指文档注释,包括类、...
  • Springboot自定义注解

    2022-03-12 14:03:21
    常见定义 a. 定义注解 @Retention 注解 功能:指明修饰的注解的生存周期,即会保留到哪个阶段。 RetentionPolicy的取值包含以下三种:... 功能:指明了修饰的这个注解的使用范围,即被描述的注解可以用在哪里。 El
  • 自定义注解详细介绍

    万次阅读 多人点赞 2018-07-10 16:03:21
    1 注解的概念 1.1 注解的官方定义 首先看看官方对注解的描述: An annotation is a form of metadata, that can be added to Java source code. Classes, methods, variables, parameters and ...
  • Java自定义注解

    2021-03-03 23:53:01
    Java 注解(Annotation)又称 Java 标注,是 JDK5.0 引入的一种注释机制。Java 语言中的类、方法、变量、参数和包等都可以被标注。和 Javadoc 不同,Java 标注可以通过反射获取标注内容。在编译器生成类文件时,标注...
  • 阿里代码规范检测中方法缺少javadoc注释怎么办发布时间:2020-08-12 15:01:48来源:亿速云阅读:204作者:小新这篇文章给大家分享的是有关阿里代码规范检测中方法缺少javadoc注释怎么办的内容。小编觉得挺实用的,...
  • 自定义生成set,get方法注释的java文件,下载后可以根据我的文章中的说明步骤进行操作。

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 26,740
精华内容 10,696
关键字:

javadoc 注解 自定义

java 订阅