Как объединить документацию по разным языкам / средам?

Question

Я проектирую библиотеку классов, предназначенную для решения широкого круга задач. Одна вещь об этой библиотеке - то, что она будет использоваться несколькими различными языками и средами изначально. Например, будет версия C++, полностью написанная на C++, версия.NET, написанная на C#, и версия Java, написанная на Java, без каких-либо зависимостей друг от друга... в отличие от написания базовой библиотеки на C++ и простого предоставления.NET и Java привязки к нему.

Библиотека в каждой из ее различных форм ставит своей целью решение различных, но иногда очень похожих задач. Например, может быть много классов, члены которых будут функционально идентичны на каждом языке, и также будет много классов, которые будут присутствовать только в одной или двух языковых версиях библиотеки, но не в других. Возьмите класс или структуру, представляющую номер версии программы..NET уже есть такой как класс (System.Version), поэтому я бы не включил его в мою версию.NET, но библиотеки C++ и Java предоставили бы ее.

Проблема, с которой я сталкиваюсь, заключается в том, что для классов, которые будут существовать в большинстве или во всех версиях библиотеки, документация будет оставаться относительно одинаковой (очевидно). Краткий текст для версии C++ и Java для структуры Version будет выглядеть примерно так: "Представляет номер версии программного обеспечения в форме major.minor.build.revision"... как и подробное описание класса и всех членов. документация и т. д. Как вы знаете, .NET, Java и C++ имеют собственный синтаксис документации. Есть ли способ, которым я могу попытаться консолидировать документацию не зависящим от языка способом (БЕЗ написания документации отдельно от исходного кода - например, ручная документация, а не генерация с использованием doxygen/sandcastle/javadoc) или я застрял при копировании и вставке один и тот же текст в исходные файлы каждой версии?

Answer 1

У меня были те же проблемы, и я решил, что есть только два варианта:

1. Использование одного и того же генератора документации на всех языках. Если вы используете doxygen (или ROBODoc, или что-то еще) для всех из них, у вас будет только один синтаксис doc для всех языков. Это означает, что вы должны порвать с языковыми соглашениями.
2. Напишите свой собственный анализатор документов. Это тяжелая работа, особенно для языка с довольно сложными синтаксическими правилами (как C++.)

В настоящее время мы используем doxygen для таких проектов.