Investigate automated documentation generation
Opened this issue · 1 comments
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
.
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.