Android注释的正确阅读与编写方式

目录

---

文章编写背景

  说来惭愧，本人是一只混日子的程序猿。在最近的工作中，突然发现自己只会用别人的东西但实际上并不完全了解，感觉自己这样子颇为智障的日子不能再继续了。于是决定开始撸源码，也开始优快云的技术贴编写之旅以便鼓励自己坚持学习，毕竟能解释好一个难点才能证明你弄懂了这个难点。

问题描述

  说到看源码，最重要的当然就是看注释了。然后发现查看官方注释的难度除了对英语的理解外，比较难懂的是一些关键字的作用，看到优快云上还比较少有大牛有写下相关的文章，为了让一些和本人一样对注释中的关键字感到疑惑的初学者看到这方面的解析，决定写下这篇文章，同时欢迎各位大牛的补充及纠错。

注释中的关键字

  相信大部分Android开发者都用过Eclipse。
  在鼠标悬停在一个类或方法上的时候，会有一个小提示窗口解释该类的作用，例如Application类：

  当然，AS也可以通过这种方式查看类的解析，只不过AS默认是关闭这个功能的，需要我们手动去打开它。

  打开AS的setting，在左侧的菜单栏依次选择Editor→General，接着可以看到以下的设置，勾选红框内的选项后点击Apply后就可以看到类的解析了。但有可能有部分朋友会发现自己的AS的类的解析像下图所示一样一直在加载中。

  导致这个问题是因为你的AS没有下载官方的文档在本地上，于是每次查看都需要去加载，而这个加载有可能是来自于官网，可能翻了墙就能秒加载。但更方便的肯定是手动下载官方文档到自己的电脑上啦，打开Default Settings，在左侧的菜单栏依次选择Appearance & Behavior→System Settings→Android SDK后再看到右侧，选择SDK Tools选项卡后看到以下场景，勾选红框内的选项后点击Apply开始加载文档。（这里可以看到我把所有的SDK工具都下载了，哈哈！[摸头]）

  这次再查看类的解析就不用在线加载了，直接读取了本地的文档，所以秒现，下图为Application类的解析。

  那么，让我们开始把注意力放到解析上，首先可以看到该类继承的类以及实现的接口是什么，然后接下来就是对该类的诠释。这些解释看起来为何那么熟悉？
  对的，没错，这正是源码中的官方注释。

  可以看到，使用”/** */”这样的注释就可以做到鼠标悬停在类名上就可以查看到解析。那么，如果有一天我们成为了技术大牛，要编写一个框架给他人使用，也可以像这样写出注释方便使用者查看。但这里，除了一些像CSS的标记外（可以使用部分CSS样式），还有一个被@link标记的字段的作用是什么呢，下面将对其作出介绍。

@link 使该类的解析可以快速打开所标记的类的本地文档中的页面，使用方式：{@link 这个里放入类或方法的全路径}。

  下面列出其它常见的标记。

@author 用来注明该类的作者。

@date 用来注明编写日期。

@version 用来注明版本号。

@since 通常用来注明某处修改或定义从什么时候开始的。

@param 用来注明方法所需的参数信息。

@return 用来注明方法返回的参数信息。

@exception 用来注明方法的异常信息。

@throws 用来注明方法的异常信息。

@see 效果和@link相似。

@deprecated 用来注明该方法已经废弃，标记后方法名会被画上一道横线。

  接下来看一下小弟的简单示例，首先先实现自己编写的一个类，加上各种注释关键字。

  然后在另外一个类里实例化上面的类并使用其方法，然后把鼠标分别悬停在该类及其方法上就可以看到注释了。

  以上是本人已了解的，欢迎各路大神进行补充及纠错。