Advice on a possible scenario

[bijington]

I am looking to do better in terms of keeping the documentation on my project up to date :).

I have an open source expression parsing/evaluating library and the general documentation covering the runtime use of it has fallen down the pecking order so I wanted to try and automate something.

The library itself is:
https://github.com/bijington/expressive

I try to provide complete XML documentation but currently that only really covers a developers use of it. The main part that I would like to automate is in somehow converting pages like this:
https://github.com/bijington/expressive/wiki/Date

to a page that could map back to the version of the library being used. This is where your library seems to possibly offer what I need however I am currently stuck trying to figure out how I can write snippets that are not actually compilable but would ideally be stored either inside the class (matching example to the wiki link above https://github.com/bijington/expressive/blob/main/Source/Expressive/Functions/Conversion/DateFunction.cs) I have implemented or at least nearby.

I have created a very basic branch/PR to try to show my lack of understanding here: bijington/expressive#105

TL-DR

I guess my initial question would be is it possible write snippets that are not code themselves?

[SimonCropp]

ok it seems that u want to use a snippet (defined in code) as an include. does that seem correct?

if so i can make a change to enable it

[SimonCropp]

then u could define the snippet as

namespace Expressive.Functions.Conversion
{
    /*
    begin-snippet: DateFunction

    Converts and returns the parameter as a DateTime.

    ```
    Date(value)
    ```

    or

    ```
    Date(value, format)
    ```

    end-snippet
    */
    internal sealed class DateFunction : FunctionBase
    {

and use it with include: DateFunction and the markdown from DateFunction would be injected

[bijington]

Wow thanks for the fast response! Sorry I missed the include documentation on my first pass through.

I think this concept could work well. One further question, would it be possible to have a single markdown template file (e.g. function template.md (happy for any keywords to go in) and then foreach different function snippet discovered it creates a resulting markdown page.

In case that part isn't clear I currently have a number of functions (e.g. Date, String, Int, etc.) If I was able to place all the documentation inside the file as you have shown in your example then I ideally wouldn't need anything specifically pointing at each function just a placeholder for any/all functions that get discovered.

Please note if there is any changes/work required to enable this functionality I would be more than happy to provide some grunt work :).