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)};

否则，如果你不想重构，你所拥有的就好了，但如果通过方法（不是公共变量）访问参数，我会查看参数并返回参数：

/**
 * 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.
}

这些参数只有在您使用方法时才能真正适用;如果int[][] people是一个公共变量，那么你所拥有的就足够了。

继续关注这一思路，正如我在评论中所提到的那样，javadoc旨在向外部（外部包）资源描述有意义的公共参数和方法，以实现它们。如果方法/参数不公开，那么正常的评论应该没问题。

真的，重要的是，您要简明扼要地了解数据中包含的内容。如果你觉得自己已经实现了这个目标，并且（更重要的是）阅读你的javadoc的人都同意，那我就说你没事。

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

1 个答案: