[Enhancement] 改善代码文档化设计
- Dominant language
- Java
- Stars
- 41.6k
- Forks
- 26.4k
- Avg merge
- 15h 13m
- Merged PRs (30d)
- 4
Description
### 背景
* Dubbo在JavaDoc方面对代码质量检查工具的支持较少
* JSR-305以及其他同类思想提出了一套改善代码检查的机制
### 收益
* 提供更好的兼容性保护
* 更好的支持java代码质量检查工具
* 更好地帮助开发者理解dubbo内部模型
### 建议新增4类注解
#### 1. null值安全类
* [@Nonnull](https://github.com/amaembo/jsr-305/blob/master/ri/src/main/java/javax/annotation/Nonnull.java)
* [@Nullable](https://github.com/amaembo/jsr-305/blob/master/ri/src/main/java/javax/annotation/Nullable.java)
#### 2. 并发类
* [NotThreadSafe](https://github.com/amaembo/jsr-305/blob/master/ri/src/main/java/javax/annotation/concurrent/NotThreadSafe.java)
* [ThreadSafe](https://github.com/amaembo/jsr-305/blob/master/ri/src/main/java/javax/annotation/concurrent/ThreadSafe.java)
* [Immutable](https://github.com/amaembo/jsr-305/blob/master/ri/src/main/java/javax/annotation/concurrent/Immutable.java)
* [GuardedBy](https://github.com/amaembo/jsr-305/blob/master/ri/src/main/java/javax/annotation/concurrent/GuardedBy.java)
```
用法是@GuardedBy(lock),这意味着有保护的字段或方法只能在线程持有锁时被某些线程访问
```
#### 3. 资源管理类
* [WillClose](https://github.com/amaembo/jsr-305/blob/master/ri/src/main/java/javax/annotation/WillClose.java)
* [WillNotClose](https://github.com/amaembo/jsr-305/blob/master/ri/src/main/java/javax/annotation/WillNotClose.java)
#### 4. 元数据类
* [Beta](https://github.com/google/guava/blob/master/android/guava/src/com/google/common/annotations/Beta.java)
```
@Beta表明一个公用API的未来版本是受不兼容变更或删除限制的
拥有这个注释标志的API不受任何兼容性保证
```
### 建议为核心模块增加package-info
例如:Guava的[package-info](https://github.com/google/guava/blob/master/android/guava/src/com/google/common/annotations/package-info.java)
### 建议适当拆分 公用API 和 厂商实现逻辑
问题:
目前 API域 和 实现域 的代码在同一个平面上,并无明确的分界特征。
使用者容易在业务代码中引用 厂商逻辑,厂商逻辑 代码随着升级而改变,就会带来兼容问题。
举个正例:
sun公司把内部逻辑放在 sun包下,把外部逻辑放在 java包 下。
这样,就能提供更好的兼容性保护。
Contributor guide
Assessment
This issue has not been assessed yet.