Javadoc写法和标签总结

Posted 2021-08-15 wodongx123

文章目录

• 1. Javadoc
• • 1.1 常用标签
  • 1.1 see, link, value
• 2. HTML标签
• 3. Kotlin的注释
• 参考材料

1. Javadoc

先说一下如何用javadoc的注释，在方法的上面输入

/**

然后在敲下回车，就会自动生成一个javadoc格式的文档，然后就可以填内容了。

那么javadoc写法的注释和我们平时用的双斜杠//的注释有什么区别呢？

最主要的区别就是javadoc的注释可以在我们鼠标放到方法名/类名/变量名上面的时候，直接看到其内容，而双斜杠的注释不行。

所以按照一般来说，我们会在类/变量/方法的注释中使用javadoc的形式，而在某段代码的注释使用双斜杠形式。

1.1 常用标签

百科上常用的标签有这些。
一般来说，author和version标签用在每个java文件中最主要的那个类上，然后param，return，see标签用在方法上。

如果项目里面的开发工具是git这种带有版本号的，author和version标签也可以不用。因为每个版本的修改信息都会附带作者和时间。

1.1 see, link, value

see标签可以指向某个类，当你想让查看这个注释的人同时去观看别的类的时候，就可以用这个标签了，鼠标放上去会自动显示那个类的quickdoc，按住ctrl再输变左键也可以直接跳转过去。

如果用上#，就可以指向类中的某个方法或者成员变量。格式是：class#method()或者class#variable，当要指向的方法/变量就是自己类内部的时候，可以省略前面的class

link标签和see标签唯一的区别就是，see标签必须要单独占一行，而link标签可以插入到注释文本中的任何地方，所以写法上会稍微有点不同，link标签的写法是：{@link class}或者{@link class#mehtod}。

value标签仅用于常量，可以直接显示出常量的值。

2. html标签

在用quickdoc的时候，会出现这样的问题，就是我们写了好几行的注释，但是在查看的时候，他们往往都没有被换行。

那是因为quickdoc在写的时候还需要使用html标签。不过javadoc也只支持部分html标签，不是全部都支持。

• br：换行用，加上这个标签注释就能换行了。
• p：分段用，但是在看的时候和br标签的区别不大，可能打包成javadoc的时候会有区别。
  
• 字体相关标签：

  b	加粗字体
  big	字体放大
  i	斜体
  s	删除线
  u	下划线
  sup	上标文本
  sub	下标文本

• 其他相关标签：
  • img：图片，没错，我们javadoc的注释是可以用图片的。用的时候注意不要把只用来注释的图片给一起编译了。
  • a：超链接，可以在注释中附加一个链接，链接到网页或者别的地方。
  • ul和li：分点标签，将注释的内容分点说明。
  • table：表格，注释里面可以使用表格。
  • code：代码。

3. Kotlin的注释

在Idea或者android Studio中，kotlin注释和Java注释本质上的差距就是：java注释的功能是编译器自带的，而kotlin的注释功能，则是插件附带的。

这就导致了一个情况，kotlin中的注释，是不能使用HTML标签的，且一部分的java标签页不能用，也就是我们无法通过br标签或者p标签来换行

1. 在kotlin中，注释要如何在quickdoc中换行呢？这点其实非常简单，只要我们加一个空行，就可以在看quickdoc的时候自动换行了。当然像是删除线等其他HTML自带的标签就没有办法使用了。
   

2. 在kotlin中，link标签和value标签也是没办法用的，但是kotlin的文档有指出要如何在注释中引用某个类/方法/变量。用中括号将类名/变量名/方法名框起来即可。
   

参考材料

HTML 标签参考手册 - 功能排序
https://www.w3school.com.cn/tags/html_ref_byfunc.asp
Kotlin 样式指南 | Android 开发者 | Android Developers
https://developer.android.com/kotlin/style-guide#documentation
javadoc_百度百科
https://baike.baidu.com/item/javadoc/4640765?fr=aladdin