Namespace Documentation feature

[a-michelis]

Even though, semantically, namespaces do not hold any value for intelisense (thus <summary> tags are not supported by namespaces), it is usually vital for documentations to provide explanatory texts in namespaces for both seamlessness and better understanding.

I currently am in a situation that requires such feature and I managed to offer it to myself by modifying the Metadata Extractor Worker with a wacky and possibly unstable workaround that kinda mimics Sandcastle's approach.

Is there any plan for implementing ways of defining Namespace summaries?

[a-michelis]

For anyone wondering what my solution was

On \src\Microsoft.DocAsCode.Metadata.ManagedReference\ExtractMetadataWorker.cs i modified the method GetMetadataFromProjectLevelCache (and the class ExtractMetadataWorker in general) as follows:

Before:

private Tuple<MetadataItem, bool> GetMetadataFromProjectLevelCache(IBuildController controller, IInputParameters key){
   // [...]
   projectMetadata = controller.ExtractMetadata(key);
   // [...]
}

After:

private Tuple<MetadataItem, bool> GetMetadataFromProjectLevelCache(IBuildController controller, IInputParameters key){
   // [...]
   projectMetadata = controller.ExtractMetadata(key);
   ExtractNamespaceDocumentation(projectMetadata);
   // [...]
}

private void ExtractNamespaceDocumentation(MetadataItem node)
{
    // Terminal nodes are not of our interest in any case
    // Even if it's a namespace, it does not contain documentation
    if (node.Items is not { Count: > 0 }) return;
    
    // If it is namespace
    if (node.Type == MemberType.Namespace)
    {
        // Get (if any), the child that is class and is named "_NamespaceDoc"
        var doc = node.Items.FirstOrDefault(x =>
            x.Type == MemberType.Class && x.Name.Split('.').Last() == "_NamespaceDoc");

        // If we didn't found such class, the namespace does not contain documentation.
        // Leave and don't go further.
        if (doc is null) return;

        // Else, assign the class' Summary and remarks to the Namespace and remove the class from the tree.
        node.Summary = doc.Summary;
        node.Remarks = doc.Remarks;
        node.Items.Remove(doc);

        // job finished for this namespace, we do not want to go further down the tree.
        return;
    }

    // For non-namespace intermediate nodes (IE assembly nodes), visit the children.
    foreach (var child in node.Items) ExtractNamespaceDocumentation(child);
}

My Project, at \.namespaces.cs :

namespace RootNamespace
{
    /// <summary>
    /// Documentation for the Root Namespace
    /// </summary>
    public static class _NamespaceDoc { }
}

namespace RootNamespace.SubFolder
{
    /// <summary>
    /// Documentation for the Root Namespace's `SubFolder` Sub-Namespace.
    /// </summary>
    /// <remarks>
    /// Remarks are also coppied...
    /// </remarks>
    public static class _NamespaceDoc { }
}

// [...]

My .csproj :

<!-- [...] -->
<ItemGroup Condition="'$(Configuration)'!='DOCUMENTATION'">
	<Compile Remove=".namespaces.cs" />
	<None Include=".namespaces.cs" />
</ItemGroup>
<!-- [...] -->

My docfx.json :

{
  "metadata": [
    {
      "src": [
        {
          "files": [
            "**.csproj"
          ],
          "src": "/my/project/root"
        }
      ],
      "[...]" : "[...]",
      "properties": {
        "Configuration": "DOCUMENTATION"
      }
    }
  ],
  "[...]" : "[...]"
}

[KalleOlaviNiemitalo]

MicrosoftDocs has namespace summaries…

• windows_foundation.md is Markdown but contains special headings like ## -description.
• ns-System.xml is XML with embedded Markdown.

I don't know whether these are handled by DocFX or by some external tools. Neither of these matches the DocFX v3 Markdown Fragments design document.

In DocFX v2, Overwrite Files might be usable for setting the summary of a namespace, but I don't remember trying that myself.

[a-michelis]

When trying to add summary to a namespace, autocompletion does not work (triple slash does not autocomplete any xml entity like summary) and DocFX v2 does not parse it either way. So, this:

will result in this:

But my method:

Will produce this:

Without including _NamespaceDoc class in both debugging or releasing

---

I do not know if namespace summary is actually supported (this way) by .NET (<summary> tags on namespaces are not included to the resulting XML file, upon building the project) and, in my understanding, that makes sense : What the compiler should do in case of a namespace having 2+ distinct summaries in different files?

I can see how my approach can be dangerous, tho.

---

About rewriting, on the other hand, since i tried it, i can confirm it works fine, but this approach does not unify code writting and documentation (which is what docfx tries to do) and does not provide any kind of intellisense (i cannot link to another documentation page unless i know the resulting HTML path and Heading ID) or even refactoring capabilities (if i change the name of my Namespace, i have to alter the .md file to point to the new Id and name).

[a-michelis]

Μy solution implies the premise that _NamespaceDoc is a class that, when defined, is used exclusively by docfx and this name cannot be changed, or used elsewere. But, adding this feature with additional switches* inside the json template could do the trick.

*by switches i mean something like

{
  "metadata": [
    {
      "[...]" : "[...]",
      "namespace":{
        "enableDoc" : true,
        "className": "_NamespaceDoc"
      }
    }
  ],
  "[...]" : "[...]"
}

[cg3y]

Since V3 is now dead to the public, now would be a good time to focus on getting this added to DocFx. Have you considered adding a pull request to incorporate? This discussion seems pretty dead, yet this is an excellent feature addition (I need namespace documentation and it's cleaner to keep in it code in the triple slash format).

[paulushub]

Overwrite Files works well, why not move to that, which is more modern.

[a-michelis]

Sorry for being late, life happened!

It is my understanding that Overwrite Files defeats the purpose of inline documentation. It works? Yes. But writing the documentation in a completely different platform works as well.

Please correct me if i'm wrong, I'd love to try new features

[Patrick8639]

It's just a matter of adding an overwrite file for each namespace.
The overwrite file must have the following format:

---
uid: <neplace with the namespace>
summary: *content
---

<Replace with the information about the namespace>

[a-michelis]

Will intelisense work on these documents as well? If yes, then that's, a totally viable option!