Как документировать арг в Java главной

Question

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

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

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

Например: «args [1] is width, args [2] is height и т. Д.».

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

Answer 1

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

Смысл: здесь нет единого правильного подхода.

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

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

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

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

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

Answer 2

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

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

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

Answer 3

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

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

Последнее утверждение резонирует именно с тем, что вы просите. Вот различные формы возможностей обработки командной строки общего CLI поддерживает:

1. POSIX как опции (т. Е деготь -zxvf foo.tar.gz)
2. GNU как длинные опции (т.е. ей --human. -readable --max глубина = 1)
3. Java как свойства (то есть. Java -Djava.awt.headless = истинное -Djava.net.useSystemProxies = верно Foo)
4. коротких варианты со значением присоединенных (то есть. НКУ -O2 foo.c)
5. длинные варианты с одним дефис (т. Е. Ant -projecthelp)

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