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

Improve ContextTask XML comments for docs #208

Closed
cjsha opened this issue Aug 13, 2024 · 2 comments · Fixed by #279
Closed

Improve ContextTask XML comments for docs #208

cjsha opened this issue Aug 13, 2024 · 2 comments · Fixed by #279
Assignees
Milestone

Comments

@cjsha
Copy link
Member

cjsha commented Aug 13, 2024

The top-level summary and remarks of ContextTask is a bit jargony. Additional description, external links, or dumbing-down might help.

image

oni.Context or oni.Frame don't seem to be valid cref values.

https://github.com/open-ephys/onix-bonsai-onix1/blob/7ac700fb8a696d4d9f8d97c9d1b85765b9951ca6/OpenEphys.Onix1/ContextTask.cs#L12-L20

Don't repeat Clock as an example for the oni.Frame.Clock and its derivatives.

image

https://github.com/open-ephys/onix-bonsai-onix1/blob/7ac700fb8a696d4d9f8d97c9d1b85765b9951ca6/OpenEphys.Onix1/ContextTask.cs#L121-L125

@jonnew
Copy link
Member

jonnew commented Sep 3, 2024

The repeated Clock, Clock issue in the above comment comes from the fact that the class name is being striped form the type. This what it looks like inside VS:

image

@cjsha
Copy link
Member Author

cjsha commented Sep 4, 2024

<see cref="BufferedDataFrame.Clock"/> is rendered into the data model by docfx as:
<xref href="OpenEphys.Onix1.BufferedDataFrame.Clock" data-throw-if-not-resolved="false"></xref>
which is subsequently converted to html as:
<a class="xref" href="OpenEphys.Onix1.BufferedDataFrame.html">Clock</a>

I know the ideal solution is to not make any edits to the comments and somehow just keep the class name, so I made an issue for this in the docs repo. This is a more long-term issue though because I'm not immediately sure how to hook into the <xref> => <a> conversion build step.

The workaround for this in the meanwhile would be to explicitly state what text you want to be in there by wrapping it in tags:

  • <see cref="BufferedDataFrame.Clock">BufferedDataFrame.Clock</see>
  • <see cref="DataFrame.Clock">DataFrame.Clock</see>

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants