Может ли doxygen связать исходный код C с разделами файла Markdown .md? - PullRequest
Новая
       104

Может ли doxygen связать исходный код C с разделами файла Markdown .md?

0 голосов
/ 28 апреля 2020

Я видел, что doxygen может использовать файл .md (Markdown) в качестве главной страницы выходной документации через настройку файла конфигурации USE_MDFILE_AS_MAINPAGE. Я также видел, что имена функций в файле .md (например, myfunc()) будут ссылаться на документацию по этой функции.

Есть ли способ обратной ссылки из исходного кода (например, заголовок функции C) на разделы файла .md?

В настоящее время я описываю несколько концепций, связанных с продуктом в исходном коде, используя специальную команду doxygen @page, и я могу заставить другой исходный код обращаться к этим страницам с помощью специальной команды @ref. Например, я могу создать @page concept My Concept и ссылаться на него откуда-либо через @ref concept. Но я бы предпочел документировать эти разделы концепции в отдельном файле, ориентированном на документацию, а не в файле исходного кода, поэтому перемещение их в файл .md выглядит логичным подходом.

ОБНОВЛЕНИЕ: ответ Альберта ниже вероятно, должно работать, но с протестированными мною версиями doxygen (1.8.11 и 1.8.13) предлагаемое решение имеет следующие проблемы:

  1. Заголовки 2-го уровня (т.е. те, которые начинаются с ##), которые включают атрибут идентификатора заголовка (например, {#label2}), больше не появляются в сгенерированном выводе doxygen и генерируют вывод: «предупреждение: найдена команда подраздела вне контекста раздела!» Это, видимо, известная ошибка. Обходной путь, который мне подходит, - это дублирование заголовка: одна строка содержит атрибут идентификатора заголовка, а другая - исключает его. Например:

    ## Header 2 {#label2}

    ## Header 2

  2. Код, который связывается с этими заголовками уровня 2 через @ref label2, не отображается на вернуться назад к указанному разделу, а не к заголовку страницы, содержащей раздел, что значительно менее полезно, если страница длинная и / или содержит несколько разделов.

ОБНОВЛЕНИЕ 2: Видимо, проблема 1 выше исправлена ​​в версии 1.8.16 и более поздней.

1 Ответ

1 голос
/ 28 апреля 2020

С разделами / страницами и др. c. в уценке также можно указать атрибут id, например: 

Header 1 {#labelid}
========

## Header 2 ## {#labelid2}

Это расширение и описано в руководстве в разделе: http://doxygen.nl/manual/markdown.html#md_header_id. На эти атрибуты id можно ссылаться, например, \ref

...