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]

I've edited my response to further strengthen my case.

The topic is Namespace Documentation feature, auto-completion has nothing to do with this as you rightly stated from the beginning

The reason for having "in-code" namespace documentation insead of simply using overwrite files (which were there when the issue was made) IS to incorporate juicy, semantically-coupled information -see usage guides which could reference multiple sub-classes of a namespace.

As the feature existed back then, why making an issue in the first place?

No, you should not document the classes in the overwrite.

I never wanted to document the classes themselves, but how various parts of the namespace can cooperate and be used in a system (or sub-system) level. And this is a completely valid approach, which, imho, is more efficient than dividing usage guide and documentation.

[paulushub]

IS to incorporate juicy, semantically-coupled information

I will think this is hardly an issue, as the DocFX extensions to markdown make any such link possible.
Also, the documentation/DocFX project is part of your project just like unit tests.

As the feature existed back then, why making an issue in the first place?

Because, it was a hack, not a .NET feature or feature extension. Using a class to document a namespace is ODD, not something many really wanted to do, and having to change the project file to specifically support this is not what many will opt for.
You are dealing with existing projects, that is understandable. Simply write a Python script to help your migration.

If what you want is something similar to Java's package-info.java, then consider something like namespacedoc tag support and argue it out with the Roslyn and/or C# Team(s). Java's support does not use a class, and XML documents are extracted by the C# compiler.

using System;

/// <namespacedoc name="LabTests">
/// Your contents here...
/// </namespacedoc>
namespace LabTests;

As pointer out by the links above, many big company will rather document all sources in external file living only developer documentations (devdoc) in the codes - such teams have dedicated documentation teams.
Previously, I think Microsoft was doing this

/// <devdoc>This is an interesting Foo class</devdoc>
/// <include file="docs.xml" path='Doc/Member[@for="MyNamespace.Foo"]/*' />
public class SomeClass { ... }

And they created the overwrite to support this type of flow.
You can see the documentation of Calendar class in ICU4J. Many companies will not want that per policy.
https://javadoc.io/doc/com.ibm.icu/icu4j/latest/index.html

[a-michelis]

The issue was created by me, back then. What I proposed is a workaround, not an actual solution to the problem.

Your suggestion about the namespacedoc tag, would be awesome, and it might be worth it giving it a try! that's what I initially thought back then, but, unfortunately, it seems like Roslyn was not passing triple slash documentation to an XML parsing procedure, but rather supported specific tags with XML like structure.

2 years ago I was way less knowledgeable, and I thought my case was a niche which only few would want, so I simply proposed the workaround to help those few people.

Now that my experience increases, tho, I find this feature all the more appealing, to the point that I return to this issue today. That said, I'm not proposing my workaround anymore, but rather want this feature to be implemented correctly -like your proposition does.

As for big corpo, #c is a language that is not only used by big corporations: I for once have made countless tools for either internal or small volume consumption. These tools, being maintained by a very small group of developers or sometimes even only by me, would greatly benefit by such a feature. And I strongly believe the open source community that uses c# on smaller projects maintained by small group of people would really love this as well.

[Patrick8639]

unfortunately, it seems like Roslyn was not passing triple slash documentation to an XML parsing procedure, but rather supported specific tags with XML like structure.

Roslyn also support any tag, as I've written a tool to post-process the generated XML file in order to support <if> conditions in the comments.
The problem is that we can't add XML documentation in a namespace declaration and thus, it doesn't export it.

A solution would perhaps be to define a class to hold all the namespace documentation (with one member for each namespace). The XML comment would contain <namespacedoc> and a post-processor would manage this to extract the namespace documentation.
To avoid having the class in the output assembly, we can can use #if to generate only when needed.

#if NamespaceDoc
sealed class NamespaceDoc
{
 /// <namespacedoc>
 /// Your contents here...
 /// </namespacedoc>
  private const Int32 LabTests = 0;
}
#endif

The information appears in the generated XML file and can be processed using a post-processor:

        <member name="F:xxx.NamespaceDoc.LabTests">
            <namespacedoc>
            Your contents here...
            </namespacedoc>
        </member>

[a-michelis]

In a way, that's what the workaround proposes. Not in the same sealed class but with different classes, but the logic is the same.

Also, yes, Roslyn is capable of parsing xml comments. What I meant is that its design does not foresee xml comments in namespace and thus doesn't attempt to retrieve/parse them.

[paulushub]

@a-michelis How about keeping this simple?

1. Add Readme.md to each namespace containing folder (so that anyone can read that and know what the namespace does)
2. You can pack these Readme files into overwrite files with scripts
3. If possible, add a pre-commit script or a git filter script to create the overwrite files.

I think this will require less changes, if any, to the project files, and can be part of the workflow.

[a-michelis]

That defeats whole in-code documentation purpose, in addition to increasing complexity, introducing custom procedures which may or may not work for every environment (ie windows vs linux users using scripts) and cause confusion to future maintainers.

Of course, you'll say "Ok, how often would you possibly wanna change namespace documentation", and yes, the answer is "not really that often". That said, it's not uncommon for procedures that are rarely initiated to be forgotten, and it's a buzkill for me. Sure, the project wont change for the likes of one quirky fella, but that's just an opinion that may help with the future of the project.

[paulushub]

That defeats whole in-code documentation purpose

As to whether namespace documentation is considered in-code document is a view that many may or not agree.
For such, you can test your view by raising it up where it will actually be implemented, and see the reactions:
Roslyn team in this case.

introducing custom procedures which may or may not work for every environment

Modern day development is a complex process, and nothing is fixed. Working with scripts to navigate
the complexity is one way to make life easier for oneself. When things change you just update your scripts.
And there is a huge job category for just that: DevOps and its related processes.
Python/JavaScript (Node-js) are now basic part of most projects, and work across platform.