java - 如何在 Javadoc 中描述数组的条目

Question

如果我有一个这样的矩阵

int[][] people = {   { 20, 18, 22, 20, 16 },
                     { 18, 20, 18, 21, 20 },
                      { 16, 18, 16, 20, 24 },
                      {  25, 24, 22, 24, 25 }};

我想在我的Javadoc中写下，每一行代表一个人，一个人的第一个条目代表他的门牌号，第二个条目代表他的年龄，...有标准的方法吗？我的尝试:

/**
 *Information about all people, every entry is an array about one person with:
 *index 0: house number
 *index 1: age
 ....

Answer 1

我会按照评论中的建议重构代码(因为数组不应该被视为顺序数据存储之外的任何东西)。关联的 javadoc(和代码)本质上看起来更加直观(甚至不需要 javadoc):

Person.java

public class Person {
    /** Their house number */
    public int houseNumber;

    /** Their age */
    public int age;

    ... // Other parameters and constructor.
        // also consider private members with getters/setters.
}

主要代码

/** A group of people. */
public Person[] people =
    { new Person(20, 18, 22, 20, 16),
      new Person(18, 20, 18, 21, 20),
      new Person(16, 18, 16, 20, 24),
      new Person(25, 24, 22, 24, 25)};

否则，如果您不想重构，您所拥有的就可以了，但如果通过方法(而不是公共(public)变量)访问它，我会查看参数和返回参数:

/**
 * Description here.
 * 
 * @return Description of return type here
 * (IE: describe the indices in this section).
 */
public int[][] getPeople() {
    return new int[][]
            {{ 20, 18, 22, 20, 16 },
            { 18, 20, 18, 21, 20 },
            { 16, 18, 16, 20, 24 },
            {  25, 24, 22, 24, 25 }};
}

/**
 * Description here.
 * 
 * @param people Describe the "people" parameter here
 * (IE: describe the indices in this section).
 */
public void setPeople(int[][] people) {
    // Do whatever using the "2D" array.
}

这些参数仅在您对方法进行 javadoc 处理时才真正适用；如果 int[][] people 是一个公共(public)变量，那么你所拥有的就足够了。

继续这个思路，正如我在评论中所回避的那样，javadoc 旨在向实现它们的外部(外部包)资源描述有意义的公共(public)参数和方法。如果方法/参数不是公开的，那么普通的注释应该没问题。

确实，最重要的是您能够简洁、连贯地表达数据中所包含的内容。如果您觉得自己已经实现了该目标，并且(更重要的是)阅读您的 javadoc 的人也同意，那么我会说您没问题。