Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: 支持接口/实体类 @see引用派生类获取扁平化字段列表信息 #15

Closed
BOFA1ex opened this issue Dec 14, 2021 · 2 comments

Comments

@BOFA1ex
Copy link
Contributor

BOFA1ex commented Dec 14, 2021

存在以下场景, 返参类型是JobDTO.
其字段content接口响应结果为向下转型后的派生类对象.
因此接口文档中关于content@object的描述需要涵盖NormalJobContentDTO/WorkflowJobContentDTO内的所有字段.

public class JobDTO {
    /**
     * 任务实例内容
     * [note]返回对象为向下转型后的派生类
     */
    private JobContentDTO content;
}

/**
 * @see NormalJobContentDTO
 * @see WorkflowJobContentDTO
 */
public interface JobContentDTO {

}

public class NormalJobContentDTO implements JobContentDTO {
    /**
     * 任务实例#field0
     */
    private Integer field0;
}

public class WorkflowJobContentDTO implements JobContentDTO {
    /**
     * 工作流实例#子任务DAG
     */
    private String dags;
}

接口文档大致如下
image

@lkqm
Copy link
Member

lkqm commented Dec 15, 2021

有两个建议的地方,你看看:

  1. see解析似乎再字段上更合理,而不是再接口上
  2. see短名称解析优化,可以参考link解析方式

@BOFA1ex
Copy link
Contributor Author

BOFA1ex commented Dec 15, 2021

@see解析似乎再字段上更合理,而不是再接口上

我这个考虑过, 最终考虑声明在类的javadoc, 具体原因如下:
JobDTO类里有JobContentDTO字段, 不代表其他类就不会引用JobContentDTO.
如果你声明@see在字段上, 就需要对多处字段进行多次声明.

@see 短名称解析优化, 可以参考link解析方式

这个我在pr #18 里已经给出review comment, 这里就不赘述了.

lkqm added a commit that referenced this issue Dec 15, 2021
@BOFA1ex BOFA1ex closed this as completed Dec 16, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants