You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
As we move towards creating DocFx documentation that pulls information directly from the source code, we should work towards full coverage of all public objects (fields / methods / properties / etc.) with both Bonsai descriptions and XML comments, where appropriate.
These two should also be slightly different; in general, Bonsai descriptions should be concise and to the point, but the XML contents can be more lengthy in their description. Part of the rationale for this is that if a user reads a description string in Bonsai and wants to learn more, the same string should not be replicated in the documentation; rather, there should be more content there for them to digest.
This should aid in pulling out details from the code so that it can be formatted into an easily readable webpage. Additionally, in the case that there is no XML comment, the Bonsai description should be pulled in to be used as a placeholder until a more extensive comment can be created.
The text was updated successfully, but these errors were encountered:
A working convention which came out of last meeting was to adopt the <remarks> markup as a hook on which to place all frontend content for the user guide. This way DocFX processing can display only the contents of <remarks> for everything, e.g. properties, process overloads, and classes.
The rest of the doc strings can be written in C# documentation style guidelines.
All types should be listed in the TOC but grouped by "category". Roughly the following categories were mentioned:
As we move towards creating DocFx documentation that pulls information directly from the source code, we should work towards full coverage of all public objects (fields / methods / properties / etc.) with both Bonsai descriptions and XML comments, where appropriate.
These two should also be slightly different; in general, Bonsai descriptions should be concise and to the point, but the XML contents can be more lengthy in their description. Part of the rationale for this is that if a user reads a description string in Bonsai and wants to learn more, the same string should not be replicated in the documentation; rather, there should be more content there for them to digest.
This should aid in pulling out details from the code so that it can be formatted into an easily readable webpage. Additionally, in the case that there is no XML comment, the Bonsai description should be pulled in to be used as a placeholder until a more extensive comment can be created.
The text was updated successfully, but these errors were encountered: