документирование библиотеки - все или только функции из публичного заголовка?

Question

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

Я склоняюсь ко второму варианту, это нормально?

Answer 1

Ответ на ваш вопрос зависит от того, кто будет читать документацию.Если документация направляется пользователям вашего API, вероятно, лучше, чтобы вы предоставили им только документацию для открытого интерфейса.Так как таким образом они не будут перегружены деталями, которые не имеют к ним отношения.

С другой стороны, если ваша документация должна быть прочитана людьми, обслуживающими библиотеку, она должна включать документацию как для публичного, так и для частногоcode.

Сейчас я использую немного другой подход к arne.У меня есть скрипт, который копирует файлы заголовков, необходимые для открытого интерфейса, в отдельный каталог для упаковки.Это необходимо в любом случае для производства релизов.Сценарий также копирует конфигурацию Doxyfile в этот каталог, а затем запускает doxygen для сокращенного набора файлов.Таким образом, у меня есть один файл конфигурации doxygen, который я использую для создания как публичной, так и частной документации.

Answer 2

Это зависит от того, хотите ли вы когда-нибудь что-нибудь изменить в этой библиотеке, скажем, через пять лет. В этом случае наличие документации может пригодиться. Тем не менее, вы должны как-то отделить вашу «личную» документацию от документации, которую вы предоставляете пользователям. Это можно сделать с помощью двух отдельных файлов конфигурации doxygen с разными входами.