Sandcastle, / doc и неуправляемый C ++

Я работаю над проектом, который использует неуправляемый Visual C ++ и немного C #. Мы пытаемся придумать способ документировать наш проект, как справку по API, так и некоторые дополнительные концептуальные документы. В идеале вся документация должна храниться вместе в файле .chm, который мы могли бы распространять вместе с нашим продуктом.

Я уже был знаком с Doxygen, как давний разработчик на C ++. Кто-то предложил мне заглянуть и в Sandcastle, но я наткнулся на несколько препятствий.

Из ряда других источников, включая другие сообщения на этом сайте, хорошо известно, что sandcastle не поддерживает неуправляемый C ++. Я нашел сообщение, которое, кажется, указывает на то, что вы все еще можете втиснуть документацию C ++ в песочный замок, добавив ссылку на API в качестве концептуальных тем.

Используя Visual Studio 2010, вы можете включить параметр / doc в настройках вашего неуправляемого проекта C ++. Это создает файлы .XDC, которые студия затем компилирует в файл .xml, который идет вместе с вашей библиотекой lib / dll / exe. Я застрял в том, что неясно, что именно вы можете делать с этим xml файлом. Некоторые страницы, которые я нашел в Интернете, предполагают, что вы можете использовать этот файл для intellisense, но я никогда не видел, чтобы это работало в неуправляемом C ++. Я надеялся, что смогу каким-то образом использовать этот XML-файл в Sandcastle Help File Builder, но я не могу найти никаких примеров того, как это делается в Интернете, и все попытки, которые я делал с SHFB, терпели неудачу. Кажется, мне нужны только файлы MAML или HTML, если я хочу добавить существующий концептуальный файл справки.

Итак, мой вопрос:

  1. Есть ли способ добавить мой / doc сгенерированный файл .xml в мое справочное решение SHFB?
  2. Если нет, то в чем смысл параметра / doc для неуправляемого C ++?
  3. Есть ли какое-то преобразование, которое я могу сделать в моем / doc-сгенерированном XML-файле для создания HTML или MAML, которые я затем мог бы импортировать через SHFB?

Может ли это сработать, или мне просто нужно вернуться в Doxygen?


visual-c++ doxygen unmanaged sandcastle shfb
person obermeister    schedule 02.01.2013    source источник

Ответы (2)


arrow_upward
3
arrow_downward

Теоретически Sandcastle можно использовать для документирования неуправляемого кода, но для этого потребуется инструмент для создания эквивалентного файла данных отражения, который в настоящее время создается инструментом MRefBuilder.exe для сборок управляемого кода. Насколько мне известно, до сих пор никто этого не делал.

Я не могу прокомментировать отсутствие IntelliSense для неуправляемого C ++, так как больше не использую его. Предположительно, / doc, вероятно, предназначен для вывода управляемого кода, если используется тот же компилятор, но с несколькими дополнительными параметрами командной строки.

Использование XSL для преобразования комментариев XML в MAML возможно, но, опять же, это вариант, о котором я не знаю, чтобы кто-либо преследовал. Я предполагаю, что в этом случае большинство предпочитают использовать Doxygen, поскольку это устоявшееся решение.

Эрик

person EWoodruff    schedule 04.01.2013

arrow_upward
2
arrow_downward

У меня похожая ситуация. Мне нужна XML-документация в моих привязках C ++ / CLI, чтобы код .NET мог видеть их с помощью Intellisense. Но к вашему сведению, Visual Studio 2010 не поддерживает XML-документацию в собственном коде:

https://msdn.microsoft.com/en-us/library/ms177226(v=vs.100).aspx

Visual Studio 2010
В Visual C ++ вы можете добавить комментарии XML-документации (с тройной косой чертой) к исходному коду и указать компилятору вывести их в файл .xml. Затем этот файл можно ввести в процесс, который создает документацию для классов в вашем коде. IDE для Visual C ++ в этой версии не поддерживает XML-комментарии в Intellisense.

Это ограничение было снято в Visual Studio 2013. Однако это по-прежнему раздражает экосистема, с которой можно работать, если вы используете шаблоны в собственном коде (например, библиотеки Boost):

В текущем выпуске комментарии кода не обрабатываются для шаблонов или чего-либо, содержащего тип шаблона (например, функция, принимающая параметр в качестве шаблона). Добавление таких комментариев приведет к неопределенному поведению.

Я нашел ваш вопрос, когда искал способ временно отключить синтаксический анализатор комментариев XML с помощью #pragma или #define при включении таких библиотек.

person Matt Chambers    schedule 03.03.2017