How to embed markdown documentation inside a working code with C type syntax for commenting?

Question

Basically I want to write one piece of text which qualifies both as a working code and MarkDown (preferably GitHub flavor) for documentation. The language I'm using has C form commenting \\ for rest-of-line and /* ... */ for multi line comments. So far what I can do is:

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

The issues are:

• the first /* still showing in the documentation
• I can't use the proper multiline code block ``` ... ```. I have to indent the code parts once more than what is required. Also the syntax highlighting doen't work in this format AFIK.

I would appreciate if you could help me know first how to solve above issues. and Secondly if there is any better way to do this?

Answer 1

I think I have a proper solution now with colapsible / foldable code section:

/*

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>

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

which will be rendered as:

/*

This is the markdown text

used for documentation

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

P.S. Implementation of the same idea using AsciiDoc here.