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.
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 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
<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.
Type files are much larger and contain all the information for a type and its members. The root of the type file is Not surprisingly, most of the documentation for an API is contained within the The For ease of authoring, To use Markdown in Do not add XML within The
<Type>, and the type uid is indicated in the
Name attribute on
<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. The next several sections describe the sub-elements of
<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.
<remarks> supports both basic XML (see Inline tags below for details) and Markdown within
!DATA as follows:
<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.
<block subset="none" type="note">. Other alert types, such as tip, warning, important, are not supported in
Not surprisingly, most of the documentation for an API is contained within the
For ease of authoring,
To use Markdown in
Do not add XML within