In general, the existing XML documentation is a good example of how to write new documentation. However, there are a few things to keep in mind when writing new documentation, that might not be immediately obvious.
In general, I would recommend developing with VSCode in mind, as that has been the standard that I have started this project in. The reason this matters is that different IDEs display a different level of documentation comments for things like hover-over tooltips.
In order to test out the changes made to any of the XML files, there is a few steps you will want to do. Firstly, you will want to have Unity open. With Unity open, navigate to Unity Preferences, External tools and then Regenerate Project Files. After doing this, you will want to restart VSCode, as it does not pick up on the XML files changing. After doing this, you should be able to see the changes in the tooltips in the TestUScript.cs file.
XML documentation is written a little different to how it normally would be done if these were generated by MSBuild. Inside the Documentation folder, each assembly will have its own folder defined for it. The name of this folder is important! its how the injector knows where to put the final documentation XML, so make sure it matches the assembly you are working for, including case! Inside each of the folders, You can create as many XML files as you would like, they will all be merged at pre-processing time. It is recommended however that you follow a standard, in this case, each XML file in a assembly folder is named after the class that it documents, for example VRCPlayerApi.xml only documents the VRCPlayerApi class.
This tag is used to specify the URL of the documentation for the current file. It is used in the following format:
<docURL>URL TO DOCUMENTATION</docURL>The injector script will format this accordingly when it pre-processes the XML file. The injector will throw a warning if this tag is missing, so it should be included on all documented members.
Defines a list of canny posts to show in the docs, in a list
Defines a canny post. Set the url attribute to the URL of the canny post, and set the inner text to a short description of the issue/post.
<cannyPosts>
<cannyPost
url="https://feedback.vrchat.com/bug-reports/p/networkingisinstanceowner-true-for-all-users">This
property is currently broken, and will always return true! use <see
cref="P:VRC.SDKBase.VRCPlayerApi.isInstanceOwner" /> instead.</cannyPost>
</cannyPosts>You might find alot of tips on how to use these characters, but most wont work due to bugs in VSCodes intellisense renderer. Here is the method ive found that works:
<![CDATA[<TEXT YOU WANT BETWEEN>]]>This should be insertable in any XML tag and it will actually render as < or > in the tooltip.
General guidelines on the different normal tags that C# XML documentation uses can be found here. One very important resource to actually writing the XML manually is This documentation. This covers the different member types and general formatting of the XML files themselves.