Support Sandcastle's behavior to recognize triple-slash on namespace

[KristianWedberg]

Triple-slash comments on the namespace itself is currently not supported. It would be great to add this, so that <summary> and <remarks> tags works, and would be presented on the API Documentation page, similar to old style MSDN pages like: http://msdn.microsoft.com/en-us/library/system.data.aspx.

Example:

/// <summary>Does not show up in .yml or .html output, but</summary>
/// <remarks>would be really nice if it did.</remarks>
namespace Boogie.On
{
}

[hellosnow]

The namespace description of old MSDN page is generated from writer's document instead of triple-slash code comments. @ansyral any idea?

[vwxyzh]

@ansyral is roslyn support it?
@KristianWedberg What about overwrite document?
e.g.:

---
uid: Boogie.On
summary: Does not show up in .yml or .html output, but
remarks: would be really nice if it did.
---

[KristianWedberg]

I just realized VS2015 doesn't use any triple-slash comments on a namespace, so I shouldn't really expect docfx to do it either.

Using an overwrite file works. Currently I would use the conceptual property for this, since using e.g. remarks does not add the expected Remarks heading.

Maybe add a comment or an example of using a namespace overwrite on the http://dotnet.github.io/docfx/tutorial/walkthrough/walkthrough_create_a_docfx_project_2.html page?

Or even better if the docfx project docs used namespace comments, and the template automatically displayed these on the top API Documentation page /api/index.html?

[ansyral]

@KristianWedberg roslyn doesn't support it, so docfx couldn't extract comments for namespaces.

[wekempf]

In Sandcastle, namespace documentation was generated by creating an internal dummy class named NamespaceDoc and putting the documentation on it.

/// <summary>Namespace documentation goes here.</summary>
[CompilerGenerated]
class NamespaceDoc
{
}

The CompilerGeneratedAttribute was used to ensure the class itself didn't wind up in the documentation.

This is another Sandcastle feature that DocFX should understand/use IMHO. External documentation files would work just as well, but the more the API reference documentation lives with the code, the better, IMHO. External documentation files should be for just that... documentation external to the API reference documentation.

[vicancy]

Hi @wekempf What is the rule for Sandcastle tell that this dummy class is for Namespace? CompilerGeneratedAttribue does not sound reliable.

[cesarsouza]

I suppose that when most people mention Sandcastle they actually mean SHFB. In this case, the rules were initially specified here: https://ewsoftware.github.io/SHFB/html/48f5a893-acde-4e50-8c17-72b83d9c3f9d.htm

It seems the only rule for the class to be recognized as a dummy class carrying namespace documentation is to be named NamespaceDoc. Then, whether it should be included or not in the actual documentation could be determined by whether this class satisfies 3 constraints at the same time: Be named NamespaceDoc, marked as [CompilerGeneratedAttribute] , and being private internal. Hopefully this could avoid excluding a class by mistake (in the rare occasion we would actually want to document a private internal compiler-generated class).

[jskeet]

The class isn't private - it can't be, as it's not a top-level class. It's internal.

[bitbonk]

In SHFB it was a PITA to add concepual documenation and it was not really possible to add additional API documentation using external doc files. Both is easy now in DocFX. I suppose you can easily add documentation for a namespace using overwrite files. I would rather not see the above mentioned ugly SHFB hack with the internal class show up in DocFX.

[cesarsouza]

Hi @bitbonk,

I agree that many things were a PITA in Sandcastle/SHFB, and that's why many projects are looking towards migrating to DocFx. However, it would be much better if some of the basic features of Sandcastle/SHFB could be supported out-of-the-box by DocFx. It doesn't mean that further updates to the documentation would have to be done in the same way as they had to be done in Sandcastle, just that the basic usage scenario (triple-slash documentation for namespaces to setup some initial documentation pages) could have been supported in the same way that other triple-slash documentation are supported as well.

Regarding SHFB's solution as "ugly hack": In my personal view, code isn't meant to be beautiful, it is meant to be useful. And I honestly think that having this current issue eventually implemented would help bringing DocFx's utility even further.

Regards,
Cesar

[cesarsouza]

I suppose that when most people mention Sandcastle they actually mean SHFB. In this case, the rules were initially specified here: https://ewsoftware.github.io/SHFB/html/48f5a893-acde-4e50-8c17-72b83d9c3f9d.htm

It seems the only rule for the class to be recognized as a dummy class carrying namespace documentation is to be named NamespaceDoc. Then, whether it should be included or not in the actual documentation could be determined by whether this class satisfies 3 constraints at the same time: Be named NamespaceDoc, marked as [CompilerGeneratedAttribute] , and being private internal. Hopefully this could avoid excluding a class by mistake (in the rare occasion we would actually want to document a private internal compiler-generated class).

[jskeet]

The class isn't private - it can't be, as it's not a top-level class. It's internal.

[bitbonk]

In SHFB it was a PITA to add concepual documenation and it was not really possible to add additional API documentation using external doc files. Both is easy now in DocFX. I suppose you can easily add documentation for a namespace using overwrite files. I would rather not see the above mentioned ugly SHFB hack with the internal class show up in DocFX.

[cesarsouza]

Hi @bitbonk,

I agree that many things were a PITA in Sandcastle/SHFB, and that's why many projects are looking towards migrating to DocFx. However, it would be much better if some of the basic features of Sandcastle/SHFB could be supported out-of-the-box by DocFx. It doesn't mean that further updates to the documentation would have to be done in the same way as they had to be done in Sandcastle, just that the basic usage scenario (triple-slash documentation for namespaces to setup some initial documentation pages) could have been supported in the same way that other triple-slash documentation are supported as well.

Regarding SHFB's solution as "ugly hack": In my personal view, code isn't meant to be beautiful, it is meant to be useful. And I honestly think that having this current issue eventually implemented would help bringing DocFx's utility even further.

Regards,
Cesar

[bitbonk]

@cesarsouza I was hoping that migrating NamespaceDoc to overwrite files or something similar would be dead simple.

If it is not, I would rather see a (well documented) migration path that makes more sense. We should not built features into DocFX just to be compatible with SHFB.

[cesarsouza]

@cesarsouza I was hoping that migrating NamespaceDoc to overwrite files or something similar would be dead simple.

If it is not, I would rather see a (well documented) migration path that makes more sense. We should not built features into DocFX just to be compatible with SHFB.

I kind of agree. So much time has passed already, and at this point, mostly everyone must have moved forward. Please feel free to close this issue if it hasn't been closed already (for some reason I am not quite sure the issue has been closed while I inspect it through github mobile).

The work on docfx has been just amazing. Thanks a lot again for having started this project!

Cheers,
Cesar