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

По сути, я хочу написать один фрагмент текста, который квалифицируется как рабочий код и как 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.

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


markdown comments literate-programming
person Foad    schedule 13.03.2019    source источник
comment
Это большой вопрос. Я хочу сделать что-то подобное для легкого грамотного программирования. Но одна из самых больших проблем, которые у меня есть, - это то, как бороться с шебангой. И другие проблемы с граничными условиями. Хотя ответ здесь является хорошей отправной точкой.   -  person Steven Lu    schedule 01.08.2020

Ответы (1)


arrow_upward
1
arrow_downward

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

/*

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
/*

The collapsible section makes sure that the documentation is clean and readable. you may see the final result here on GitHub. I used the code from here. Now there are a bunch of /*s and */s which would be nice to get ride of. Next step would be to modularize the MarkDown document into different files as I have asked here.

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

person Foad    schedule 13.03.2019
comment
Я думаю, что решение будет зависеть от того, какой парсер Markdown используется (например, из-за обработки встроенного HTML), но рад, что у вас что-то работает. - person ShreevatsaR; 14.03.2019
comment
правда. это отображается только на github и vscode, но не на Stackoverflow и Typora. - person Foad; 14.03.2019
comment
Я смог немного изменить это, имея возможность правильно скрыть начальный */, отображаемый в блоках кода, и иметь возможность отображать // или //////////// в начале файла (что нормально, поскольку вы можете использовать его как украшение) но кажется неизбежным иметь их на концах блоков кода, чего я терпеть не могу ... Это меня немного расстраивает, потому что в остальном это довольно способно. - person Steven Lu; 02.08.2020