标签: code-documentation

我已经浏览了这个论坛,我用Google搜索了这个,我不确定处理同一类中出现的Javadoc和注释的最佳方法是什么.

从我从Sun/Oracle的文档中可以看到,他们似乎建议(尽管我真的找不到一个明确的陈述)Javadoc应该在注释的顶部列出.

请参阅他们的示例如何以及何时弃用API.

这对于像@Deprecated或@Override这样简单的东西非常有用.但是,如果你使用JPA和/或Hibernate呢？您的类和方法必须更加注释(有时每个类或方法有两个或更多注释).

我猜Javadoc仍然在注释之上？

另外我想知道如何最好地使用注释？我已经看到了一些示例,其中注释"堆栈"在类,成员,方法之上.我已经看到其他人在同一行列出注释(通常是这里的方法).

哪个最好？哪个更具可读性？

你是否"记录"了你在Javadoc中注释某些内容的事实？

我正在寻找一套关于这方面的好文档和/或你自己对最易读/可维护的经验.

提前道歉,这是我真正想到的,我可以在网上找到,但我遇到了麻烦.

在Python中,在标题部分,我看到有时人们会用美元符号($)包装他们的文字.从示例来看,似乎这是一个指向填充自动更新信息的指针(可能是通过源代码控制？),但我不明白它是如何工作的.

例如:

__version__ = '$Revision: 4799 $'.split()[1]
__date__ = '$Date: 2006-09-25 11:09:02 -0400 (Mon, 25 Sep 2006) $'.split()[1]
__author__ = 'John Doe FIX: put in the authors name'

是我在(Python示例文档模板 )中找到的 示例.所以$围绕着版本(随着时间的推移而改变)和日期(也会改变).假设它是某种指针,总是捕获有关版本,日期等的最新信息,有人可以指出我这是如何工作的吗？哪个源代码控制软件使用这种语法？跨语言是否相同？

谢谢!

我正在尝试自动化 JS 库中的特定模块，但陷入了我想要定义一组属性的点（假设一个对象作为类的构造参数）。

/**
 * This function initiates world peace!
 * @constructor
 * @param {object}  defaults        - The options to initiate peace.
 * @param {number}  defaults.issues - The number of issues being taken up.
 * @param {string}  defaults.source - The name of the location where process starts.
 */
 var WorldPeace = function (defaults) {
     // code here
 };

如果构造的所有属性都在一个位置定义，那就太好了。不幸的是，我的代码有许多模块有助于构建属性。可以说，在代码的其他部分（在后面的文件中）会导致具有更多属性

 * @param {Date} defaults.start  - The date when the process started.
 * @param {Date} defaults.stop   - The date when the process …

对于 Groovy 或 Java 类或方法，我通常会在文档注释（也称为 Javadoc 注释）中包含任何 API 级文档，而不是常规注释。添加有关 Groovy 脚本的此类注释的类似方法是什么？

我个人不太关心 Javadoc 工具是否获取文档。然而，有关 Groovy 脚本用途的文档在概念上似乎类似于类的文档注释；因此，我直觉地希望它们出现在文档评论中。如果我的直觉是错误的并且文档标签不是注释 Groovy 脚本意图的标准方式，那么记录脚本用途的首选方法是什么？

我目前正在测试 Dokka 文档，我所做的一些注释没有被渲染。以下是我的发现：

1. 类不显示@sample, 和 html 标签<p></p>, <h1></h1>: 请参阅 SimpleCalculator类文档
2. 如果描述位于 html 标签下，则不会显示：请参阅enum class OPERATOR代码文档
3. 方法根本不显示@sample：@property请参阅所有方法代码文档
4. @property和之间的定义混合@param。在类声明中， the@param是 a 内的那个<>（例如Group<T>）。但在方法中，它是参数内的那个。

请看我的代码：

package example

/**
 * <h1> A Simple Calculator for your daily needs! </h1>
 *
 * <p> This class can help you add, subract, multiply and divide Integers </p>
 *
 * @property firstNumber the first Number you want to …

我正在玩代码文档和实时模板,我很不明白.

我已经阅读了Dr.Bob关于生成有关实时模板的文档和维基文章的文章,但我对类描述有一个问题.

通过类描述我理解当我将鼠标光标指向类声明时的IDE行为.

例如,我有这样的类与它的描述:

type
  {$REGION 'TMyClass'}
    /// <summary>
    /// Summary works
    /// </summary>
    /// <remarks>
    /// Remarks works
    /// </remarks>
    /// <exception cref="www.some.link">This works</exception>
    /// <list type="bullet">
    /// <item>
    /// <description>description does not work</description>
    /// </item>
    /// <item>
    /// <description>description does not work</description>
    /// </item>
    /// </list>
    /// <permission cref="www.some.link">This works</permission>
    /// <example>
    /// <code>
    /// Code example does not work
    /// </code>
    /// </example>
  {$ENDREGION}
  TMyClass = class
  private
    a, b, c: Integer;
  public
  end;

后来在代码中我有这样的声明: …

我一直在使用Xcode 5的能力,用支持的注释语法记录我的代码(参见这个问题).Xcode 6使用Objective-C源支持它,遗憾的是没有使用Swift源.

我想在.swift源代码上执行内联文档.知道如何做或最佳做法？

提前致谢,

路易斯

为ReactJS无状态函数编写注释的推荐方法是什么？

假设我有以下代码:

export const LoginForm = ({ submitting, handleSubmit }) => (
  <form onSubmit={handleSubmit(submit)}> ...(code)... </form>
));

文档评论应该如何？

我的第一个想法是:

/**
 * Form for user login
 * @param {bool} submitting Shows if form submitting is in progress
 * @param {function} handleSubmit Form submit callback function
 */

但是,这是不是为正确submitting而handleSubmit不是真正的PARAMS LoginForm功能.它们只是props参数的关键.另一方面,记录props为参数LoginForm似乎毫无意义,因为每个反应组件都有props一个参数,而道具键是函数最重要的部分.

有官方指导方针吗？(我没找到)

编辑

我还PropTypes定义了:

LoginForm.propTypes = {
  submitting: PropTypes.bool,
  handleSubmit: PropTypes.func.isRequired,
};

也许这是道具相关文档的地方？如果是这样,应该怎么样？那有什么标准吗？

复制FindBin::libsPerl 6中的行为.

  (1) Start from `$Bin`.
  (2) Search for `./lib` dir's above it.
  (3) prefix them to the search list.

在P6中,这需要管理$*REPO,我认为需要使用CompUnit::RepositoryRegistry,但我在modules.perl6.org(可能因为它是核心)或docs.perl6.org上找不到任何文档.

问:CompUnit::RepositoryRegistry使用一些新目录作为前缀管理列表是正确的$*REPO吗？

问:如果是,记录在哪里CU::RR？

问:如果没有,我应该使用什么？

谢谢

给定enum具有case带参数的 ，我如何记录这些参数？

例如这些代码注释：

/// Various coffee types.
enum Coffee {

  /// A Cappuccino.
  /// - parameters:
  ///   - cream: Is true if cream is added.
  case cappuccino(cream: Bool)
}

生成缺少cream参数文档的弹出窗口。

那么什么是正确的标记？