Java 新手 - 一般 JavaDoc 问题

Posted 2023-02-21

【中文标题】Java 新手 - 一般 JavaDoc 问题

【英文标题】：New to Java - general JavaDoc issues

【发布时间】：2017-06-13 21:33:18

【问题描述】：

此处的一般 JavaDoc 问题： 我怎么知道他们是否在工作？我知道格式和他们应该做什么，但我怎么知道他们是否在做他们的工作？编译运行后是否应该打印出来？

另一个问题 - 我需要多少 JavaDoc cmets？我的教授真的希望我们在这些评论中检查我们的方法，并解释任何变量。这是否意味着将其放入方法中？还是在方法之前但在类内部？还是上课前？

感谢您的帮助！

【参考方案1】：

我认为您可能对 JavaDoc 的实际作用有点困惑。

无论如何，JavaDoc 不会直接影响您的程序。 JavaDoc 是一种编译程序信息的方法。假设您有一个程序并希望以一种方便的格式记录它的功能。像 eclipse 这样的常见编译器可以选择编译一个包含文档的 html 文件，就像它在 Java API 文档中显示的那样。 https://docs.oracle.com/javase/7/docs/api/ 这大部分都是 JavaDoc，它是从 cmets 生成的。

我的老师总是告诉我关于 cmets，你不是在为不读代码的人评论。你不需要像....这样的cmets。

// Prints out hello world
System.out.println("hello world");

程序员已经知道这个功能。程序员对参数名称和函数的实际作用更感兴趣。示例

/**
* @param a Number we are dividing into
* @param b Number we are dividing by
* @return Our quotient
*/
public static float divide(int a, int b) 
return (a/b); 

会生成这样的页面 强调顶部的/**，两个星号表示下面包含JavaDoc。像 Eclipse 这样的大多数 IDE 都会突出显示 JavaDoc。 如您所见，参数的名称只有 a 和 b，在某些情况下，很难通过其功能来标记参数名称，因此可以节省时间使用 JavaDoc 来描述它们，而不是使用某人滚动浏览您的代码，试图弄清楚它们到底在做什么。您正在为您的程序创建一个指南来修改和更新它。

JavaDoc 从字面上看是所有函数、类、变量如何在程序中工作的指南。