Как встроить документацию по уценке в рабочий код с синтаксисом типа C для комментирования? - PullRequest
Новая
       40

Как встроить документацию по уценке в рабочий код с синтаксисом типа C для комментирования?

0 голосов
/ 13 марта 2019

В основном я хочу написать один фрагмент текста, который квалифицируется как рабочий код и MarkDown (предпочтительно GitHub) для документации.Язык, который я использую, имеет форму C, комментирующую \\ для остатка строки и /* ... */ для многострочного комментария.Пока что я могу сделать: 

/* --> start with multi line comments 
here some markdown text
# heading
 * list

end markdown section with
<!--- */ // -->
or
[//]: # (end of comment block --> */ // <-- inline comment)

_-_-indented code
_-_-_-_-more indented code

Проблемы:

  • первый /* все еще отображается в документации
  • Я не могуиспользуйте правильный многострочный кодовый блок ``` ... ```.Я должен отступить части кода еще раз, что требуется.Также подсветка синтаксиса не работает в этом формате AFIK.

Буду признателен, если вы поможете мне сначала узнать, как решить вышеуказанные проблемы.и во-вторых, есть ли лучший способ сделать это?

1 Ответ

1 голос
/ 13 марта 2019

Я думаю, что у меня сейчас есть правильное решение с разделом складного / складного кода: 

/*

This is the markdown **text** 

used for documentation

<details>
  <summary>Click to see the source code</summary>

``` scilab 
*/
This is the
  actual code
  which will 
be executed
/*
```

</details>

<!--- */ // -->

, который будет отображаться как:

/ *

Это уценка текст

используется для документации 

*/
This is the
  actual code
  which will 
be executed
/*

Складная секция обеспечивает чистоту и удобочитаемость документации.Вы можете увидеть окончательный результат здесь, на GitHub .Я использовал код от здесь .Теперь есть куча /* и */ с, на которых было бы неплохо прокатиться.Следующим шагом будет модуляризация документа MarkDown в другие файлы, как я и просил здесь .

PS Реализация той же идеи с использованием AsciiDoc здесь .

...