Есть сторонний проект вообще без док. Как-то не очень с ним разбираться, хочется куда-то записывать то, что узнал о проекте, его классах, методах, функциях и тп. В идеале бы чтобы это скушал Доксиген и выдал мне худо бедно доку. При этом хочется, чтобы если в проекте что-то меняется — допустим, я класс описал на стороне, а в проекте он изменился — то Доксиген бы мне сигналил, что дока перестала соответствовать сорцам. Как бы что-то такое сделать?
Здравствуйте, Marty, Вы писали:
M>Здравствуйте!
M>Есть сторонний проект вообще без док. Как-то не очень с ним разбираться, хочется куда-то записывать то, что узнал о проекте, его классах, методах, функциях и тп. В идеале бы чтобы это скушал Доксиген и выдал мне худо бедно доку. При этом хочется, чтобы если в проекте что-то меняется — допустим, я класс описал на стороне, а в проекте он изменился — то Доксиген бы мне сигналил, что дока перестала соответствовать сорцам. Как бы что-то такое сделать?
Можно внешние тесты прикрутить.
Т.е. к каждой статье doxygen-а прилагать .cpp файл unit-test-ов, который тестирует исполнение описанных инвариантов.
Это уже не doxygen, хотя сборку и тестирование можно включить в туже единицу сборки, что и документация.
Re: А можно ли Доксигеном документировать проект отдельно от кода?
Здравствуйте, Marty, Вы писали:
M>Здравствуйте!
M>Есть сторонний проект вообще без док. Как-то не очень с ним разбираться, хочется куда-то записывать то, что узнал о проекте, его классах, методах, функциях и тп. В идеале бы чтобы это скушал Доксиген и выдал мне худо бедно доку.
А смысл использовать Доксиген отдельно? Что должен делать Доксиген в этом "отдельном" случае?
Ну Латех используй
Изменения в исходниках по сравнению с документацией вообще никакой продукт не отслеживает.
Включая Доксиген.
Течёт вода Кубань-реки куда велят большевики.
Re[2]: А можно ли Доксигеном документировать проект отдельно от кода?
Здравствуйте, alpha21264, Вы писали:
A>А смысл использовать Доксиген отдельно? Что должен делать Доксиген в этом "отдельном" случае?
Ну, хочется подсовывать со стороны сигнатуру функции или метода с именем класса и пространства имен, я её сам задокументирую, а доксиген бы только ругался, если в сорцах такой не нашлось — что-то поменялось.
Ну, или как-то так. Не знаю
Здравствуйте, alpha21264, Вы писали:
A>Изменения в исходниках по сравнению с документацией вообще никакой продукт не отслеживает.
go doc отчасти отслеживает. Конечно, актуальность твоего текста в комментариях он не может ни осознать ни, следовательно, проверить. Но прототипы функций, имена типов, переменных и констант и т.п. он из кода берет, а не из комментария, и они всегда актуальны.
А golint может проверить, что все публичные символы содержат комментарий, и он хоть начинается с имени того символа, к которому относится.
В обчем, есть системы и поосмысленнее доксигена. Собственно, до знакомства с Go я был искренне убежден, что любая автогенеримая документация годится только для отправки в помойку не читая. Но у Go она вообще вся автогенеримая, и при этом весьма вменяемая. Иногда даже на какую-нибудь сишную библиотеку, посмотришь на доку, ничего не понятно, посмотришь на доку от ее Гошной обертки, и становится понятно.
Re: А можно ли Доксигеном документировать проект отдельно от кода?
Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, and to some extent D. Doxygen also supports the hardware description language VHDL.
Кроме того, можно ему подсовывать файлы с описанием в его формате, и он из этого сделает отдельную страницу. В идеале так и надо делать, а не только сигнатуры подтягивать + коменты к ним.
Но в вашем случае можно посмотреть на другие решения, например тот же markdown формат с его дальнейшей конвертацией хоть в HTML, хоть в пдф. Про латех уже выше советовали — тоже вариант.
