Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Consider adding comments and Bonsai descriptions to all public objects #107

Closed
bparks13 opened this issue Jun 6, 2024 · 1 comment · Fixed by #162
Closed

Consider adding comments and Bonsai descriptions to all public objects #107

bparks13 opened this issue Jun 6, 2024 · 1 comment · Fixed by #162
Assignees
Labels
documentation Improvements or additions to documentation proposal Request for a new feature
Milestone

Comments

@bparks13
Copy link
Member

bparks13 commented Jun 6, 2024

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.

@bparks13 bparks13 added the proposal Request for a new feature label Jun 6, 2024
@glopesdev glopesdev added this to the 0.1.0 milestone Jul 2, 2024
@glopesdev glopesdev added the documentation Improvements or additions to documentation label Jul 2, 2024
@glopesdev glopesdev self-assigned this Jul 2, 2024
@glopesdev
Copy link
Collaborator

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:

  • Headstage / Hub nodes
  • Single device nodes
  • Enums
  • Data frames / Types (other)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation proposal Request for a new feature
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants