Комментарии автоматической генерации документации
В некоторых языках, появившихся относительно недавно,
появились комментарии автоматической генерации документации.
В языке Java этот вид комментариев начинаются символами «/**» и заканчиваются символами «*/».
В Python такие комментарии начинаются и заканчиваются тремя двойными апострофами «"».
Такой подход — хорошая идея.
Если такие комментарии документирования можно использовать как 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 13:39
Отзывы
2012/10/05 08:24, utkin #
В C# также есть подобные комментарии.
2016/03/20 10:49, rst256 #
Doxygen, а лучше CWEB хотя CWEB это уже совсем иной взгляд на документирование кода.
2016/03/21 14:28, Автор сайта #
Doxygen .. работает подобно компилятору, анализируя исходные тексты и создавая документацию. Т.е. в него надо ещё свой анализатор вкладывать, настраивать на свой язык? А если основной формой хранения программы будет некое нетекстовое промежуточное представление, то будут сложности?
2016/08/06 18:55, rst256 #
А если основной формой хранения программы будет некое нетекстовое промежуточное представление, то будут сложности? Нет это проблем не вызовет, все равно для нового языка нужно будет написать свой анализатор. Добавить свой отзыв
Написать автору можно на электронную почту mail(аt)compiler.su
|