Adds a docfx documentation file, and documentation for ControlBackend#617
Adds a docfx documentation file, and documentation for ControlBackend#617bclehmann wants to merge 5 commits intoScottPlot:masterfrom
Conversation
|
Hey @Benny121221,
I strongly agree! I like the idea of having documentation in code, especially to assist developers extending this work. I also like how documentation can be tracked in version control this way (one of the reasons I generate the cookbook the way I do). However, I think it's not the best timing to roll this out right now. I've been putting a lot of work into transitioning from 4.0 to 4.1 (#605) which just got merged, but touched almost every file in the project, and I'm continuing to refactor lots of primary components (including user controls, which will use non-blocking rendering, and a shared control backend). I do want to take advantage of documentation in code (and tools like docfx), but I think I should wait until the new version begins to stabalize more before I do... |
|
Following-up, I've been working adding a lot of the XML docs as part of #738 so this might be more feasible soon Related, I just found this tool which is pretty interesting. It generates documentation automatically from NuGet packages |
|
Interesting, that looks easier than setting up docfx (or something similar). It looks like you've already implemented your own solution in #727 and I think it's good that it's part of the website instead of external. |
2 participants
New Contributors:
please review CONTRIBUTING.md
Purpose:
If you're unfamiliar, docfx is a tool which allows creating websites from documentation comments (
///or/**).New Functionality:
This PR adds docfx documentation (which for most code files is merely a list of method signatures and the like). For files with Javadoc comments, those are featured in the documentation webpages.
Install docfx and run
docfx ./dev/docfx_project/docfx.jsonto build the documentation. If you want to start the server, rundocfx ./dev/docfx_project/docfx.json --serveMy only qualms are I don't know how this fits with the existing cookbook documentation. I believe some parts of ScottPlot are best documented through traditional documentation (such as
ControlBackend), but plottables and the like are best documented through the cookbook. Regardless, I think documentation would help the project, even if just through IDE tooltips.Perhaps it needn't be quite as overkill as this (from
ControlBackend.cs):Personally, I think that such documenting is appropriate for that file, as it's intended to help other people implement their own user controls, it isn't some implementation detail buried out of sight. But I'm not sure it's necessary (nor worth the effort) to document every file so rigorously.