Java Language
Документирование кода Java

algorithm Android HTML javafx JavaScript MySQL Regular Expressions spring spring-boot SQL

Вступление

Документация для Java-кода часто создается с помощью javadoc . Javadoc был создан Sun Microsystems с целью генерации документации API в формате HTML из исходного кода Java. Использование формата HTML дает удобство гиперссылки связанных документов вместе.

Синтаксис

/ ** - запуск JavaDoc в классе, поле, методе или пакете
@author // Чтобы назвать автора класса, интерфейса или перечисления. Требуется.
@version // Версия этого класса, интерфейса или перечисления. Требуется. Вы можете использовать макросы, такие как% I% или% G%, для программного обеспечения для управления исходным кодом, которое необходимо заполнить при оформлении заказа.
@param // Чтобы показать аргументы (параметры) метода или конструктора. Укажите один тег @param для каждого параметра.
@return // Чтобы показать типы возвращаемых значений для непустых методов.
@exception // Показывает, какие исключения могут быть выбраны из метода или конструктора. Исключения, которые ДОЛЖНЫ быть пойманы, должны быть перечислены здесь. Если вы хотите, вы можете также включить те, которые не нужно захватывать, например ArrayIndexOutOfBoundsException. Укажите одно исключение @ для каждого исключения, которое может быть выбрано.
@throws // То же, что @exception.
@see // Ссылки на метод, поле, класс или пакет. Используйте в виде package.Class # что-то.
@since // Когда этот метод, поле или класс были добавлены. Например, JDK-8 для класса, такого как java.util.Optional <T> .
@serial, @serialField, @serialData // Используется для отображения serialVersionUID.
@deprecated // Чтобы пометить класс, метод или поле как устаревшие. Например, будет java.io.StringBufferInputStream . Смотрите полный список существующих устаревших классов здесь .
{@link} // Подобно @see, но может использоваться с пользовательским текстом: {@link #setDefaultCloseOperation (int closeOperation) см. JFrame # setDefaultCloseOperation для получения дополнительной информации}.
{@linkplain} // Похож на {@link}, но без шрифта кода.
{@code} // Для буквенного кода, например, HTML-тегов. Например: {@code <html> </ html>}. Однако это будет использовать моноширинный шрифт. Чтобы получить тот же результат без моноширинного шрифта, используйте {@literal}.
{@literal} // То же, что и {@code}, но без моноширинного шрифта.
{@value} // Показывает значение статического поля: значение JFrame # EXIT_ON_CLOSE равно {@value}. Или вы можете ссылаться на определенное поле: Использует имя приложения {@value AppConstants # APP_NAME}.
{@docRoot} // Корневая папка JavaDoc HTML относительно текущего файла. Пример: <a href="{@docRoot}/credits.html"> Кредиты </a>.
HTML разрешен: <code> «Привет cookies» .substring (3) </ code>.
* / - конец объявления JavaDoc

замечания

Javadoc - это инструмент, входящий в состав JDK, который позволяет конвертировать комментарии в коде в документацию HTML. Спецификация Java API была сгенерирована с использованием Javadoc. То же самое можно сказать и о большей части документации сторонних библиотек.

Документация по классу

Все комментарии Javadoc начинаются с комментария блока, за которым следует звездочка ( /** ) и заканчивается, когда комментарий блока ( */ ). При желании каждая строка может начинаться с произвольного пробела и одной звездочки; они игнорируются при создании файлов документации.

/**
 * Brief summary of this class, ending with a period.
 *
 * It is common to leave a blank line between the summary and further details.
 * The summary (everything before the first period) is used in the class or package 
 * overview section.
 *
 * The following inline tags can be used (not an exhaustive list): 
 * {@link some.other.class.Documentation} for linking to other docs or symbols
 * {@link some.other.class.Documentation Some Display Name} the link's appearance can be 
 * customized by adding a display name after the doc or symbol locator
 * {@code code goes here} for formatting as code
 * {@literal <>[]()foo} for interpreting literal text without converting to HTML markup 
 * or other tags.
 *
 * Optionally, the following tags may be used at the end of class documentation 
 * (not an exhaustive list):
 *
 * @author John Doe
 * @version 1.0
 * @since 5/10/15
 * @see some.other.class.Documentation
 * @deprecated This class has been replaced by some.other.package.BetterFileReader
 * 
 * You can also have custom tags for displaying additional information.
 * Using the @custom.<NAME> tag and the -tag custom.<NAME>:htmltag:"context"
 * command line option, you can create a custom tag.
 *
 * Example custom tag and generation:
 * @custom.updated 2.0    
 * Javadoc flag: -tag custom.updated:a:"Updated in version:"
 * The above flag will display the value of @custom.updated under "Updated in version:"
 *
 */
public class FileReader {
}

Те же теги и формат, используемые для Classes могут также использоваться для Enums и Interfaces .

Методическая документация

/**
 * Brief summary of method, ending with a period.
 *
 * Further description of method and what it does, including as much detail as is 
 * appropriate.  Inline tags such as
 * {@code code here}, {@link some.other.Docs}, and {@literal text here} can be used.
 *
 * If a method overrides a superclass method, {@inheritDoc} can be used to copy the 
 * documentation
 * from the superclass method
 *
 * @param stream Describe this parameter.  Include as much detail as is appropriate
 *               Parameter docs are commonly aligned as here, but this is optional.
 *               As with other docs, the documentation before the first period is 
 *               used as a summary.
 *
 * @return Describe the return values.  Include as much detail as is appropriate
 *         Return type docs are commonly aligned as here, but this is optional.
 *         As with other docs, the documentation before the first period is used as a 
 *         summary.
 *
 * @throws IOException Describe when and why this exception can be thrown.
 *                     Exception docs are commonly aligned as here, but this is 
 *                     optional.
 *                     As with other docs, the documentation before the first period 
 *                     is used as a summary.
 *                     Instead of @throws, @exception can also be used.
 *
 * @since 2.1.0
 * @see some.other.class.Documentation
 * @deprecated  Describe why this method is outdated. A replacement can also be specified.
 */
public String[] read(InputStream stream) throws IOException {
    return null;
}

Полевая документация

/**
 * Fields can be documented as well.
 * 
 * As with other javadocs, the documentation before the first period is used as a
 * summary, and is usually separated from the rest of the documentation by a blank 
 * line.
 * 
 * Documentation for fields can use inline tags, such as:
 * {@code code here}
 * {@literal text here}
 * {@link other.docs.Here}
 * 
 * Field documentation can also make use of the following tags:
 * 
 * @since 2.1.0
 * @see some.other.class.Documentation
 * @deprecated Describe why this field is outdated
 */
public static final String CONSTANT_STRING = "foo";

Пакетная документация

Java SE 5

В Javadocs можно создать документацию на уровне пакета, используя файл package-info.java . Этот файл должен быть отформатирован, как показано ниже. Ведущие пробелы и звездочки необязательные, обычно присутствующие в каждой строке для форматирования причины

/**
 * Package documentation goes here; any documentation before the first period will 
 * be used as a summary.
 *
 * It is common practice to leave a blank line between the summary and the rest
 * of the documentation; use this space to describe the package in as much detail
 * as is appropriate.
 * 
 * Inline tags such as {@code code here}, {@link reference.to.other.Documentation},
 * and {@literal text here} can be used in this documentation.
 */
package com.example.foo;

// The rest of the file must be empty.

В приведенном выше случае вы должны поместить этот файл package-info.java в папку пакета Java com.example.foo .

связи

Связывание с другими Javadocs выполняется с помощью тега @link :

/**
 * You can link to the javadoc of an already imported class using {@link ClassName}.
 *
 * You can also use the fully-qualified name, if the class is not already imported: 
 *  {@link some.other.ClassName}
 *
 * You can link to members (fields or methods) of a class like so:
 *  {@link ClassName#someMethod()}
 *  {@link ClassName#someMethodWithParameters(int, String)}
 *  {@link ClassName#someField}
 *  {@link #someMethodInThisClass()} - used to link to members in the current class
 *  
 * You can add a label to a linked javadoc like so:
 *  {@link ClassName#someMethod() link text} 
 */

С тегом @see вы можете добавлять элементы в раздел « См. Также ». Подобно @param или @return место, где они появляются, не имеет значения. Спектр говорит, что вы должны написать его после @return .

/**
 * This method has a nice explanation but you might found further
 * information at the bottom.
 *
 * @see ClassName#someMethod()
 */

Если вы хотите добавить ссылки на внешние ресурсы, вы можете просто использовать тег HTML <a> . Вы можете использовать его в любом месте или внутри обоих тегов @link и @see .

/**
 * Wondering how this works? You might want
 * to check this <a href="http://stackoverflow.com/">great service</a>.
 *
 * @see <a href="http://stackoverflow.com/">Stack Overflow</a>
 */

Создание Javadocs из командной строки

Многие IDE обеспечивают поддержку для генерации HTML из Javadocs автоматически; некоторые средства сборки (например, Maven и Gradle ) также имеют плагины, которые могут обрабатывать создание HTML.

Однако для создания Javadoc HTML эти инструменты не требуются; это можно сделать с помощью инструмента командной строки javadoc .

Самое основное использование инструмента:

javadoc JavaFile.java

Что будет генерировать HTML из комментариев Javadoc в JavaFile.java .

Более практичное использование инструмента командной строки, который будет рекурсивно читать все java-файлы в [source-directory] , создавать документацию для [package.name] и всех подпакетов и размещать сгенерированный HTML в [docs-directory] является:

javadoc -d [docs-directory] -subpackages -sourcepath [source-directory] [package.name]

Документация по встроенному коду

Помимо кода документации Javadoc можно документировать встроенный.

Комментарии Single Line начинаются с // и могут быть размещены после оператора в той же строке, но не раньше.

public void method() {
  
  //single line comment
  someMethodCall(); //single line comment after statement
  
}

Многострочные комментарии определяются между /* и */ . Они могут охватывать несколько строк и могут быть помещены между операторами.

public void method(Object object) {
  
  /*
    multi 
    line 
    comment
  */
  object/*inner-line-comment*/.method(); 
}

JavaDocs - это специальная форма многострочных комментариев, начиная с /** .

Поскольку слишком много встроенных комментариев могут уменьшить читаемость кода, их следует использовать редко, если код недостаточно понятен или дизайнерское решение не является очевидным.

Дополнительным вариантом использования однострочных комментариев является использование TAG, которые являются короткими ключевыми словами, основанными на соглашениях. Некоторые среды разработки признают определенные соглашения для таких комментариев. Обычными примерами являются

//TODO
//FIXME

Или укажите ссылки, то есть для Jira

//PRJ-1234

Фрагменты кода внутри документации

Канонический способ написания кода внутри документации - с конструкцией {@code } . Если у вас есть многострочный код, завершающий внутри <pre></pre> .

/**
 * The Class TestUtils.
 * <p>
 * This is an {@code inline("code example")}.
 * <p>
 * You should wrap it in pre tags when writing multiline code.
 * <pre>{@code
 *  Example example1 = new FirstLineExample();
 *  example1.butYouCanHaveMoreThanOneLine();
 * }</pre>
 * <p>
 * Thanks for reading.
 */
class TestUtils {

Иногда вам может потребоваться ввести сложный код внутри комментария javadoc. Знак @ является особенно проблематичным. Использование старого <code> рядом с конструкцией {@literal } решает проблему.

/**
 * Usage:
 * <pre><code>
 * class SomethingTest {
 * {@literal @}Rule
 *  public SingleTestRule singleTestRule = new SingleTestRule("test1");
 *
 * {@literal @}Test
 *  public void test1() {
 *      // only this test will be executed
 *  }
 *
 *  ...
 * }
 * </code></pre>
 */
class SingleTestRule implements TestRule { }

Modified text is an extract of the original Stack Overflow Documentation

Лицензировано согласно CC BY-SA 3.0

Не связан с Stack Overflow