There are several types of public APIs we expose and their documentation is written in different ways:
APIs in Microsoft.ReactNative
These are WinRT APIs. The documentation for these used to be manual but it is now autogenerated.
To add/change one of these APIs' documentation
- find the type definition in the IDL file
- rebuild Microsoft.ReactNative.sln (in Debug, see below)
- pass it through the doc generator tool (
winmd2markdown) to produce the markdown files and IntelliSense XML - check the produced markdown files into the react-native-windows-samples repo
Syntax
Here are the available syntax features that will be surfaced by the doc generator tool:
[doc_string("my string")]will add a description string. This gets compiled unconditionally into the WinMD file, so since we want to limit the size of our binaries, we have aDOC_STRINGmacro that compiles to no-op on Release builds, and adds the attribute in Debug. As a result, only Debug builds should be used to auto-generate the markdown docs.[doc_default("the_default_value")]can be applied to properties to document their default value[experimental]will mark the API or type as experimental. You will get build warnings for any API/types that are not marked experimental but reference an experimental API/types.[deprecated("This is deprecated, use something else", deprecate, version_number)]will mark the API as deprecated and store the message.
You can use a special syntax to cross-link to a type or property/method within a type, inside of a doc_string / deprecated string:
@MyLinkedTypewill link to the page forMyLinkedType.@MyLinkedType.MyPropertywill link to theMyPropertyanchor in theMyLinkedTypepage.@.MyPropertywill link to theMyPropertyanchor in the current page.
Note: when adding code samples, ensure that // comments are instead replaced with /-/. This is because MIDL first calls the C preprocessor which will strip comments before MIDL gets a chance to interpret them as part of a string.
Features
- For every type (class, struct, enum, delegate), the tool will produce a single markdown file with all its members in a way that is consumable by Docusaurus (which the samples repo uses).
- It uses the text supplied to
doc_stringanddoc_defaultand adds it as the description of the type or API. - Every time a type is mentioned (e.g. when we display the type of a property, a return type of a method or the types of the params, etc.) it will produce a clickable link that will take you to either the corresponding markdown page if the type is in the same namespace, or to the docs.microsoft.com page for the type (if it is a
Windows.*orMicrosoft.*type). - Displays Experimental / Deprecated notices. To enable outputting experimental APIs, pass
/experimentalin the command line. - Every class will list any non-trivial interfaces that it implements (and link to it)
- Tracks back-references to each type. This way people can figure out "if I wanted to use this type, what other types have APIs that reference it?", and they can better understand e.g. how to get an instance of this type by using other APIs.
- Creates an additional page that links to all the types it crawled. In the samples repo API page, the sidebar only lists a few APIs plus the Full reference page for access to the full set of APIs.
The XML generation uses the same metadata:
- Produces an IntelliSense XML with a
<summary>section based on thedoc_string - If it encounters code blocks (
```), it will add them as a<example><code>...section.
Usage
The doc generation tool will produce both markdown files (one per type) as well as an IntelliSense XML that can be added to the NuGet package.
C# code using the Microsoft.ReactNative winmd directly, can leverage the IntelliSense XML and get doc comments that way.
C++ code won't get the doc comments right now but @asklar has work underway to support this - essentially we need to:
- Standardize the custom MIDLRT attributes into Windows.Foundation.Metadata
- Have cppwinrt produce XML docs in the projected code that is seeded from the custom attributes
- move the RNW code to use the now-standardized custom attributes instead of doc_string.
Validating API Docs for a Release
Before integrating the auto-generated API docs into the react-native-windows-samples-repo, we want to make sure that any new API's for the current release candidate have been appropriately documented.
- Walk through the .idl files in the microsoft/react-native-windows.
- For .idl files that have changes in 0.68 make sure that all API's have a corresponding
doc_string.
Integration into the react-native-windows-samples repo
The PR/CI builds will produce an artifact called "WinMD API docs". This is a zip file of the markdown and IntelliSense XML files we need. For a stable branch, make sure the samples repo has not been cut already (i.e. we should not already have a website\versioned_docs\version-0.xx for the appropriate version).
- Download the WinMD API docs artifact zip file.
- Delete all of the
*api-windows*files in the appropriate \docs\native-api folder. This will delete some of the JS API docs, so you'll undelete those in a second. - Copy the markdown files from the zip to this folder.
- Review the list of docs (in the VS Git tab or something like sdvdiff), undelete the ones that are for JavaScript APIs.
Note: If the version-0.XX folder exists already, you will need to manually update the page id's for the *-api-windows pages such that the id field has the prefix version-0.XX- and a third field original_id is added with the original contents of the id field.
Screenshots
Regular page
Deprecation notice
Full reference page
Back-references
C++ APIs
The most commonly used C++ APIs we have used outside of the RNW repo are macros used by native module implementers, like REACT_MODULE. These are currently only documented as part of the Usage docs
APIs in Microsoft.ReactNative.Managed
These APIs provide a more convenient, idiomatic C# access to the React Native for Windows WinRT APIs in Microsoft.ReactNative. Since the code is written in C#, the APIs can be documented using XML comments.
The managed attributes like [ReactModule] live in this namespace. They are leveraged by Microsoft.ReactNative.Managed.CodeGen to generate code-behind that deals with registering native modules.
Windows-only React Native JavaScript/TypeScript APIs
These are hand-written, though with some work they could be generated. They live in the samples repo.
Usage docs
These are hand-written, They live in the samples repo.