Skip to content

Add API documentation to Cookbook#727

Merged
swharden merged 10 commits intomasterfrom
api-documentation
Feb 1, 2021
Merged

Add API documentation to Cookbook#727
swharden merged 10 commits intomasterfrom
api-documentation

Conversation

@swharden
Copy link
Member

This PR seeks to automatically generate API documentation and add it to the Cookbook. It also allows tests to test for documentation. This will be achieved by a combination of reflection and XML parsing.

Closes #726

@bclehmann
Copy link
Member

I wonder if adding an annotation such as [PublicAPI] would be a good way to specify which classes get included in the XML documentation.

You could do something like [PublicAPI(Category="Plottables")] to split the classes up into categories if need be?

@swharden
Copy link
Member Author

@bclehmann interesting idea! I thought about this for a bit, and will probably lean away from it. I do see their potential value in that they could add a lot of functionality, and most interestingly be a nice way to define which public methods are described on which documentation pages.

However, I'm generally am not a big fan of custom attributes for public code bases because people can't quickly hop in the code and know how to make new properly-annotated methods. This was the primary reason I really didn't like the use of attributes to define "data validation" behavior in plottable code (#533), and more recently am apprehensive about requiring the whole code base to have special attributes to provide back-compatible nullable annotations (#691).

Custom attributes can add a lot of potential functionality, but they increase the learning curve for people new to the code base, and I'm trying to make this library as simple to jump into as possible. There are a few pockets of complexity still (e.g., the tick system) but I hope to slowly massage those out with time.

@swharden
Copy link
Member Author

swharden commented Jan 31, 2021

I'm amazed how difficult this turned out to be. I think it's starting to look nice though. It makes it easier to identify parts of the API that could use improvement. This is what the markdown looks like:
https://github.com/ScottPlot/ScottPlot/blob/d35e183048132d35ce5687781f8ae182adb7bac2/dev/API-Plot.md

EDIT: https://github.com/ScottPlot/ScottPlot/blob/31ab5f973aefdec59f2dc4d2f5bcb43fe5bc53c9/dev/API-Plot.md

@swharden swharden marked this pull request as ready for review February 1, 2021 01:33
@swharden swharden merged commit 0f69bd0 into master Feb 1, 2021
@swharden swharden deleted the api-documentation branch February 1, 2021 01:34
This was referenced Feb 1, 2021
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 this pull request may close these issues.

Add API Documentation to Cookbook

2 participants