Комментарии автоматической генерации документацииВ некоторых языках, появившихся относительно недавно,
Такой подход — хорошая идея. Если такие комментарии документирования можно использовать как help, то это просто здорово! Употреблённые внутри функции, они попадают в справку для этой функции. Если такой вид комментария встречается внутри класса, то он попадает в справку для этого класса. Пример на Python:
def DumpOpen(file):
"""
Takes one argument (the input file) and opens it for reading
Returns a list full of data
"""
openedFile = open(file, "r")
data = openedFile.readlines()
cleanedData = []
for line in data:
cleanedData.append(line.rstrip())
openedFile.close()
return cleanedData
В программе на языке Java комментарии документации могут появляться перед
классом, объявлением интерфейса, методом, конструктором или объявлением поля.
На основе этих комментариев может быть сгенерирована (как вариант) web-страница с документацией.
Отказываться от такого удобства в будущих языках программирования неразумно. Опубликовано: 2012.09.25, последняя правка: 2014.12.20 10:39
Отзывы
Doxygen .. работает подобно компилятору, анализируя исходные тексты и создавая документацию. Т.е. в него надо ещё свой анализатор вкладывать, настраивать на свой язык? А если основной формой хранения программы будет некое нетекстовое промежуточное представление, то будут сложности?
А если основной формой хранения программы будет некое нетекстовое промежуточное представление, то будут сложности? Нет это проблем не вызовет, все равно для нового языка нужно будет написать свой анализатор.
Если честно, то я лично не понимаю — а почему для этих целей нельзя использовать обычные многострочные комментарии, ведь они для того и пишутся, чтобы документировать код??? Разные цели документирования: можно документировать интерфейс или реализацию. Документация интерфейса — это то, как пользоваться некоторой сущностью (функцией, классом, модулем, библиотекой…), она не касается того, как устроена сущность. Документация реализации — так как эта сущность устроена. Первая документация нужна, если мы просто хотим вызывать некоторую функцию, вторая — если мы хотим саму функцию модернизировать. И первое требуется гораздо чаще, чем второе.Например, для функции сортировки нам нужно знать, как передавать ей набор сортируемых объектов, как передавать критерий сортировки, как получается результат (набор переупорядочивается на месте или строится новая коллекция, уже отсортированная), стабильна сортировка или нет, какая асимптотика алгоритма. Этого всего нам достаточно, чтобы написать вызов функции sort(). А какой алгоритм реализован внутри функции сортировки, нам нужно знать только на момент написания этой функции. Или оптимизации, если выяснится, что программа тормозит из-за медленной сортировки. Поэтому разумно разделять два вида комментариев и для комментариев интерфейса формировать документ с описанием API (например, в виде HTML). Для некоторых языков особые документирующие комментарии могут быть избыточны. Например, для языка Си документирующие комментарии можно размещать в .h-файле, а комментарии реализации — в .c. Для Java, наоборот, нужны, т.к. отдельных файлов, где описывается интерфейс, в Java нет. Написать автору можно на электронную почту |
2012/10/05 08:24, utkin