Doc string facility в C++

Question

Языки, такие как Python, MATLAB, E-Lisp, имеют прекрасное средство для doc-строк. С помощью этой функции, используя всего несколько нажатий клавиш в терминале, вы можете получить документацию о функциях/модулях, которые вы написали и импортировали в свой код.

Теперь есть ли «метод» (библиотека, редактор трюки, независимо в), чтобы получить аналогичный объект в C++/С Предположим, я включаю документацию функции в исходном файле на главу функции , , тогда я хотел бы набрать команду, например getinfo, на терминале. (что-то как страница человека)

Я знаю, что такая функция «человек» существует для многих функций C, но документация для этих функций написана в отдельных текстовых файлах из исходного кода. Я хотел бы, чтобы документация была на месте

Answer 1

Вы можете использовать что-то наподобие Doxygen. Он поддерживает создание man pages, среди других форматов.

Answer 2

Если вы отметили свой код комментариями в синтаксисе, подобном Javadoc, вы можете создать документацию для своего кода в различных форматах, используя Doxygen. Он может генерировать, среди прочего, man-страницы, но кажется, что предпочтительный пользовательский формат вывода использует HTML-страницы.

Answer 3

Visual Studio может/будет генерировать всплывающие окна, содержащие информацию, извлеченную из DocXml форматированных комментариев. Вы должны скомпилировать с /doc, который будет извлекать XML из комментариев в файл .xdc. Затем вам нужно запустить xdcmake, чтобы скомпилировать файлы .xdc в xml-файл. Вы обычно обрабатываете все это автоматически в процессе сборки, поэтому вам не нужно делать много вручную (за исключением самих комментариев, конечно). Единственное, что нужно иметь в виду, это то, что код (по крайней мере, декларация) должен быть создан до того, как вы получите всплывающие окна.

Я чувствую себя обязанным добавить, что ИМО, большинство таких комментариев, как правило, очень близки к бесполезным. Если корпоративный стандарт делает их неизбежными, пусть будет так, но если они честно предоставляют какую-либо полезную информацию, я бы подумал, что это указывает на проблему («Запах кода», если вы предпочитаете эту формулировку). В большинстве случаев комбинация имени функции (или любого другого) и имен/типов параметров должна сделать использование функции совершенно ясной.