Как документировать args в Java main

Как вы собираетесь документировать содержимое параметра args в:

public static void main(String[] args) {
    ...
}

Я не спрашиваю о том, как использовать тег блока @param в javadoc, но вместо этого как документировать, каково должно быть содержимое каждого элемента в массиве.

Например: "args [1] - ширина, args [2] - высота и т.д.".

Есть ли <ol><li></li></ol> путь?

Ответ 1

Вы можете сделать это неофициальным способом, записав в свой javadoc текст, описывающий аргументы ожидаемые.

Значение: здесь нет единого правильного подхода.

Другими словами: вы должны использовать этот вариант, который лучше всего подходит для вас, и других людей в вашей команде/проекте.

Если ваша команда teamleguide позволяет (спрашивает?) использовать HTML-теги в javadoc, то используйте теги HTML. Если у вашей команды есть более сложный подход, который позволяет использовать какой-то язык разметки, тогда используйте это. В противном случае вы, вероятно, должны использовать только {@code}, чтобы выделить определенные части.

Короче говоря: здесь нет точного правила; поэтому вы должны соответствовать тем, которые лучше всего соответствуют вашим потребностям.

Но имейте в виду: возможно, javadoc не так важен. Если вы считаете, что ваше приложение используется напрямую из командной строки, то основное внимание должно быть уделено тому, что что-то вроде "java -jar yourjar --help" дает разумный результат. И что вы не заново изобретаете колесо с точки зрения анализа аргументов. Другими словами: существует довольно много библиотек, которые можно использовать для разбора командной строки. И я уверен, что они должны иметь поддержку для документирования потенциальных аргументов для пользователей командной строки.

Я говорю следующее: в "нормальной" настройке я ожидал бы, что те, кто заинтересован в вызове вашего основного метода, будут читать не javadoc. Они хотят посмотреть какой-то экран справки, чтобы понять, какие варианты они могут использовать!

Ответ 2

Вы находитесь на границе рамки Java. Аргументы main предоставляются средой выполнения хоста в виде массива символов. Вам нужно будет написать код, чтобы определить значение этих строк. Для других методов, которые вы пишете, вы, вероятно, объявите несколько аргументов для представления каждого ввода этого метода и используйте синтаксис @param javadoc для документирования каждого аргумента.

Посмотрите, как это делают другие: String.format - Хотя это использует синтаксис vararg, он находится под капотом, преобразованным в массив.

Чтобы ответить на ваш вопрос: нет единственного правильного способа сделать это.

Ответ 3

Вы можете взглянуть на документацию apache-commons-cli, которая служит общей библиотекой для кли-обработки через сообщество Java,

Библиотека CLI Apache Commons предоставляет API для команды синтаксического анализа которые передаются программам. Он также может печатать справочные сообщения подробно описывая параметры, доступные для инструмента командной строки.

Последнее утверждение резонирует именно с тем, что вы просите. Вот различные формы возможностей командной строки, которые поддерживает common-cli:

  • Параметры, подобные POSIX (например, tar -zxvf foo.tar.gz)
  • GNU как длинные параметры (т.е. du --human-readable --max-depth = 1)
  • Свойства, подобные Java (например, java -Djava.awt.headless = true -Djava.net.useSystemProxies = true Foo)
  • Короткие опции со значением (gcc -O2 foo.c)
  • длинные опции с одним дефем (т.е. ant -projecthelp)

Если вы хотите выполнить свою собственную реализацию, вы все равно можете получить намек на их документацию.