Authoring Managed Reference in ECMAXML

ECMAXML files contain both API structure and signature information and documentation. They are created via reflection from DLLs and, optionally, XML comment files (ideally consumed via NuGet packages). Therefore they can be 100% sourced from code, if only XML comments are used, or they can be authored or augmented by editing them directly.

The best practice for managed reference documentation is to use source code as the single source for all or most documentation. That is, complete comments should be authored and maintained in the source code as part of the development process, built into the XML comment files, and updated each time reflection runs. Only rich content, such as remarks and examples, should be authored directly in ECMAXML. However, it is possible to edit all documentation directly in ECMAXML, and this topic provides instructions for doing so.

Warning

Any part of an ECMAXML file, including API signature information, can be edited and committed to GitHub - we do not yet have validation to prevent edits to non-documentation fields. However, edits to non-documentation fields can result in inaccurate or broken documentation, and will be over-written at the next reflection. If you find signature or structural errors in a managed reference docset please file an issue via http://SiteHelp for investigation. ONLY edit ECMAXML documentation fields as described in this topic.

Each ECMAXML file represents one namespace or type.

Namespace files

Namespace files name begin with ns- and the files contain minimal content: just the <Namespace> element with a Name attribute indicating the namespace uid, and a <Docs> element with <summary> and <remarks>. By default after reflection, these elements contain "To be added." Note that the OPS build strips this boilerplate if you do not edit it, but adding at least a summary for every namespace is recommended.

namespace ECMAXML

Type files

Type files are much larger and contain all the information for a type and its members. The root of the type file is <Type>, and the type uid is indicated in the Name attribute on <Type>. The element also contains a <Docs> element, which contains the type-level documentation, and a <Members> element that contains a <Member>element for each member of the type. Each <Member> contains its own <Docs>element.

Not surprisingly, most of the documentation for an API is contained within the <Docs> element. The next several sections describe the sub-elements of <Docs>.

Docs

Remarks

The <remarks> section is for detailed information about a namespace, type, or member, often multiple paragraphs. This section is often not included in source code because it can get quite long and does not render in IDEs; it is also often open to internal and external contribution.

For ease of authoring, <remarks> supports both basic XML (see Inline tags below for details) and Markdown within !CDATA.

To use Markdown in <remarks>, add !DATA as follows:

Note

Do not add XML within !CDATA sections.

Summary

The <summary> is a brief description of the namespace, type, or member - usually just 2 - 3 sentences. This is core documentation and the best practice is to author and maintain it in the source code and add it to ECMAXML via reflection. However, you can edit summaries directly in ECMAXML.

  • Use basic XML. See Inline tags below for details.
  • For multiple paragraphs, use <para>.
  • For links, use <cref>.
  • For notes, you can use <block subset="none" type="note">. Other alert types, such as tip, warning, important, are not supported in <summary>.

Inline tags

See also

ECMAXML Full Documentation