comments - 如何使用 C 类型语法将 markdown 文档嵌入到工作代码中以进行注释？

Question

基本上我想写一段文本，既可以作为工作代码，也可以作为文档的 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 中不起作用。

如果您能先帮助我了解如何解决上述问题，我将不胜感激。其次，是否有更好的方法来做到这一点？

Answer 1

我想我现在有一个带有可折叠/可折叠代码部分的合适解决方案:

/*

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>

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

将呈现为:

/*

这是 Markdown 文本

用于文档

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

可折叠部分确保文档清晰易读。你可能会看到最终结果here on GitHub .我使用了 here 中的代码.现在有一堆 /* 和 */ 可以很好地利用它们。下一步是按照我的要求将 MarkDown 文档模块化为不同的文件 here .

P.S. 使用 AsciiDoc 实现相同的想法 here .