Feature Request: optionally include source details on API pages

[SilentSin]

It wouldn't always be desirable, but in projects where you distribute the source code it would be helpful to users to be able to see the file path of the source file for whatever part of the API they are looking at. A line number would be nice too.

[SilentSin]

It could even be nice to be able to include the actual raw source file on the API page for scripts that are being released for free anyway. I'm not sure what the best way would be to specify which files this should apply to. A globbing pattern in the config file could do it, but it might be nicer if you could specify it in the actual source files so you always have explicit control over exactly which files it is used for.

[LokiMidgard]

With scripts do you mean like sample code? Something like this:

public class MyRealCoolFrameworkClass {
// ...
    [DocumentationCode(Title:"Initial Steps to use this Library", Category:"Sample")]
    [Conditional("Documentation")]
    private void HowToUse() {
        // Create a new Instance
        var obj = new MyRealCoolFrameworkClass();
        // Insert aditinal sample code here...
    }
}

Which then would add a sample section to the documentation with the title Initial Steps to use this Library and those three lines of code.

Or do you want complete files to be shown in the documentation?

[SilentSin]

Including simple bits of example code can already be done with <example> and <code> tags. I'm talking about including the full raw source script for situations where the script will be released freely anyway.

I'm putting together lots of examples to show the usage of the plugin I'm documenting and a lot of them contain nothing public (only private serialized fields and private methods which Unity calls using something like reflection) so their API pages end up looking like this:

[daveaglick]

A technique I’ve see used in other .NET documentation tools is to specify a source file and region (literally a #region) to insert. We could also consider letting you specify a method since Roslyn can figure that out.

There are definitely plans for this (might even be an existing issue). I’ve also got Big Ideas around the new Try .NET stuff that was announced last week.

[SilentSin]

Big Ideas™

Using #regions doesn't seem like the right approach to me, but targeting a specific method could be interesting. Especially if it would be possible to put an attribute or some sort of tag in the XML comment of any member to indicate that it should include its own source in the documentation (rather than everything needing to explicitly specify itself as the target).

Try .NET sounds awesome. Probably totally useless for Unity stuff, but I could imagine it being really useful in other environments.