Megabit
[Docs] Automate API documentation
Not a priority. However, we could investigate how to generate API documentation for each component. We could use XML comments for all needed information
- https://github.com/loxsmoke/DocXml
One problem I see with automation is that we don't know which public methods must be mentioned and which not. Not all public methods should be used by the user. We might add an additional comment to them, like "Should be used only internally", and then skip those.
Could we use the [EditorBrowsable] Attribute, and when generating docs, use reflection to filter out those members?
If we don't want the user to use those public methods anyway, we could hide them, so someone who does not know about their existence, will not use them.
All public members that should be used are already marked as Parameter Attribute. Methods are a bit different, so we need to find another way. I would not add more attributes for now.
I see, what do we have more of? public methods that are internal Blazorise use only? or public methods that are for users only?
we could use a custom xml element for marking our methods BlazoriseInternal maybe?
/// <summary>
/// Some method description
/// </summary>
/// <blazorise-internal/>
public void SomeMethod();
My idea is to have a comment convention that indicates the method is only for internal use. Then, we can just filter out those.
/// <summary>
/// Some method description. It should not be used externally.
/// </summary>
public void SomeMethod();
This way, we know what to filter, and the user knows that if they use it, it may not work as expected, because the same comment can show up in IntelliSense.