@rbuckton Does the DocFX template have support for namespaces yet? If so, then we could eliminate this awkward workaround and generate proper pages for them.

For an example of how this is currently getting rendered, take a look at: https://docs.microsoft.com/en-us/javascript/api/office?view=excel-js-preview#office-initialize

No, it does not. We would have to submit a PR to dotnet/docfx for this change.

I've mentioned this before, but I have a workaround I use for https://github.com/esfx/esfx that involves changes to support namespaces properly:

• yamlDocumenter.js
• UniversalReference.common.js
• namespace.tmpl.partial (NOTE: I redesigned the template organization to make it easier to tinker with)

Example: https://esfx.js.org/esfx/api/equatable/comparable_namespace.html#equatable_Comparable_Namespace

Have you considered opening a PR for DocFX itself? I think everyone who uses TypeScript namespaces would be greatly appreciative of this change.

I planned to do so eventually, but not until my schedule has settled down.

If the DeclarationReference already is namespace qualified, could you leverage that? I'm thinking of adding some additional utility methods/properties to the DeclarationReference API to make that even easier.

This is not really a DeclarationReference. It's a title that is shown in the document, in a specific context.

I'm thinking of adding some additional utility methods/properties to the DeclarationReference API to make that even easier.

@rbuckton In order to integrate this into the TSDoc parser, we will need to integrate it into NodeParser, and the objects need to replace the earlier DocDeclarationReference AST node type.

Ideally we would do that in a way that eliminates the need for a standalone DeclarationReference API. We can follow up about this separately.

No worries, was just thinking about whether the DeclarationReference could be reused for this because it already supports the dot-qualified formatting, but I wouldn't worry about changing anything here.

My thought had been to add a few members to DeclRef and related objects:

• isFullyQualified - true if the DeclRef has no missing components (:function, :constructor, :index, :call, :new, and :complex would also require an overload index), otherwise false
• isReachable - true if the DeclRef contains no Local (~) navigations, otherwise false.
• isStatic - true if the DeclRef contains only Static (.) navigations, otherwise false.
• isInstance - true if the DeclRef contains any Instance (#) navigations, otherwise false.
• namespaceQualifiedName - Returns the string value of the DeclRef's symbol excluding any meaning or overload index:
  • my-package:a.b.c:member -> a.b.c
  • my-package:a.b.c:class -> a.b.c
  • my-package:a.b.c:function(1) -> a.b.c
  • NOTE: I considered replacing # with .prototype. for this as well...
• namespaceName - Returns the string value of the DeclRef's symbol excluding the outermost ComponentPaths that do not represent a namespace member, meaning, or overload index (i.e. my-package:a.b.c:member -> a.b).
  • NOTE: This would have been a good use case for enummember, as an enummember is kind of member-like and kind of a var-like export of its containing namespace...
  • my-package:a.b.c:member -> a
  • my-package:a.b.c:class -> a.b
  • my-package:a.b.c:var -> a.b
  • my-package:a.b.c:namespace -> a.b
• classQualifiedName - Similar to namespaceQualifiedName, but only includes the containing class name for members:
  • my-package:a.b.c:member -> b.c
  • my-package:a.b#c:member -> b#c
  • my-package:a.b.c:var ->
  • my-package:a.b:constructor -> b
• className - Gets the name of the containing class/interface/enum:
  • my-package:a.b.c:member -> b
  • my-package:a.b#c:member -> b
  • my-package:a.b.c:var ->
  • my-package:a.b:constructor -> b
• name - Gets the name of the symbol:
  • my-package:a.b.c:member -> c
  • my-package:a.b.c:class -> c

Then you could have done something like:

const namespaceName = apiItem.canonicalReference.namespaceName
return (namespaceName ? namespaceName + '.' : '') + Utilities.getConciseSignature(apiItem);
// or, if `Utilities.getConciseSignature` is updated to return only the argument list...
return apiItem.canonicalReference.namespaceQualifiedName + Utilities.getConciseArgumentList(apiItem);

• my-package:a.b.c:member -> b.c
• my-package:a.b#c:member -> b#c

It might be nice to have a standardized API for rendering names, especially if they may contain problematic characters like ECMAScript symbols, quoted strings, or overloads.

However, I'm unsure whether the DeclarationReference API should try to solve a problem that is really about documentation formatting. For example, although # and (2) are important operators in the {@link} notation, I'm not sure they will look nice on the documentation website. Utilities.getConciseSignature() returns (arg1,arg2) instead of the overload index because it's a better documentation experience, despite being a worse design for the UID requirements.

If we have my-package!myNamespace.MyClass#staticMember(2), the kinds of strings we'd want from a doc formatting API might be more like this:

• myNamespace (namespace)
• myNamespace.MyClass (class)
• MyClass (class)
• staticMember(arg1,arg2)
• MyClass.staticMember(arg1,arg2) (static)

The api-extractor-model API might be a better place to implement this, since it has access to information like whether the parent is a namespace or not, and what are the argument names.

Even though they can't collide, looking at this kind of makes me want to have :property, :accessor, :method, and :enummember, but this is probably fine.

We want this to be the same notation that humans use when creating {@link} tags, though. Inexperienced developers may have trouble understanding the distinction between an :accessor versus a :property, and they may wonder why an :enummember is treated specially.

Most of the selector names are easy to learn because they correspond to the TypeScript keyword that introduces them (e.g. constructor, var, function, etc). Thus people can learn that :member is the catch-all for constructs that don't have a natural TypeScript keyword. (The :index and :call selectors are the only exceptions to this rule, but they are uncommon and somewhat special as they don't have an identifier.)

Any concern with TOC collisions with class C { static x; x; }? Both would have the TOC display name of x with no disambiguation.

Does DocFX create TOC entries for class members? I didn't think it did.

I'm not sure at the moment, but you may have to disambiguate other items in the TOC, such as merging a function or a variable and an interface with the same name. I had to workaround this for esfx: https://github.com/esfx/esfx/blob/bbc36650efa6a88c9d998b0dafb53e8421513898/scripts/docs/yamlDocumenter.js#L214-L216