Investigate automated documentation generation

[bijington]

The wiki approach has a nice clean design however it is painful to finish let alone keep up to date. I quite like the idea of adding in verbose descriptions to functions that would then allow something like docfx to generate something useable from.

e.g.

internal sealed class AddDaysFunction : FunctionBase
{
    /// <summary>
    /// Returns the supplied date/time with the specified number of days added.
    /// </summary>
    /// <example>
    /// This sample shows how to add 2 days to #today#.
    /// <code>
    /// AddDays(#today#, 2)
    /// </code>
    /// </example>
    public override object Evaluate(IExpression[] parameters, Context context)
    {
        ...
    }
}

NOTE this does not have to rely on using docfx but some level of auto generation would be nice to reduce maintenance effort.

Also note that the above would need a mechanism to discover the actual parameters required and not parameters and context.

[graniero]

Love it!

Using the triple-slash documentation comments would make the documentation immediately available in Visual Studio's IntelliSense, and you'd have a whole range of auto-generation tools to choose from, so you could find something that nicely fits your current workflow or pipeline.

It also opens up some nice future possibilities: if you do move towards more of a 'function bundle' approach for mix-and-match extensibility, you would be well set up to bring community-contributed functions or bundles into your 'official' ecosystem and have their documentation automatically mesh into the primary documentation.