Skip to content

Documenting your code with mdoc

Jump to bottom
Matthew Leibowitz edited this page Sep 14, 2020 · 6 revisions

This project uses mdoc to document types, members, and to add small code snippets and examples.

Each pull request should contain useful mdoc documentation for all public types and members. This consists of new or updated mdoc files inside of the /docs/en/* directory of the repository which has entries for all public api's.

To simplify the process, we have a msbuild target that can be run to generate xml file placeholders:

  1. The mdoc target will only add/update placeholders and not remove them for public types and members, so it's important to make sure your public api code is final before running the target.

  2. Run msbuild /m /restore /v:m /t:rebuild;mdocupdatedocs /p:Configuration=Release /p:ContinuousIntegrationBuild=false Xamarin.Essentials/Xamarin.Essentials.csproj which will update existing mdoc xml files and generate new ones for new types.
    Or use Cake: dotnet cake --target=docs

  3. You can edit the .xml files in any text editor. The DocWriter tool can be used to help make editing these files a bit easier.

  4. Commit your xml file changes as part of your pull request.

What to write

  1. If a method throws an exception please document this in the Remarks area.
Clone this wiki locally