Conversation
|
I wonder if adding an annotation such as You could do something like |
|
@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. |
|
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: |
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