What is the problem this feature would solve?
-
Libraries often deprecate features or develop new best practices over time. Helping LLMs understand what the current best practices and features to use are is important.
-
Libraries also do not want to maintain separate API docs from those already contained in their source code for publishing to the web (or other mediums).
-
Doc comments in source code are also essential to providing a robust editor experience for consumers, so adding in components like <llms-exclude> is impractical.
-
Sometimes users intentionally want deprecated/old-pattern recommendations due to current usage in their application
An integration that enables llms documentation to be generated that takes into account information about current best-practices and deprecations that is already contained within source code documentation would be ideal for helping to robustly solving this problem and helping guide LLM users towards using best practices.
What is the feature you are proposing to solve the problem?
I think there's two features this plugin requires to support a great story for api documentation
- multiple output channels.
Channels would be configurable. For instance if an app configures two channels modern and with-legacy then four files would be produced:
- llms-full-modern.txt
- llms-full-with-legacy.txt
- llms-modern.txt
- llms-with-legacy.txt
- configurable transformers
Transformers would be functions that take in a source file + a channel list and produce the a new "file" for each channel for the plugin to use.
In practice, how this would allow the problem to be solved:
Consider Typedoc, a leading solution for generating robust API documentation from source code, and which via its markdown plugin offers a quick integration with vitepress. Typedoc uses tsdoc/jsdoc tags (such as @deprecated) to produce meta information and sections in the resulting markdown.
A two channel configuration + transformer could check for the presence of Deprecated on items in the file and either remove them or keep them based on the channel.
What alternatives have you considered?
No response
What is the problem this feature would solve?
Libraries often deprecate features or develop new best practices over time. Helping LLMs understand what the current best practices and features to use are is important.
Libraries also do not want to maintain separate API docs from those already contained in their source code for publishing to the web (or other mediums).
Doc comments in source code are also essential to providing a robust editor experience for consumers, so adding in components like
<llms-exclude>is impractical.Sometimes users intentionally want deprecated/old-pattern recommendations due to current usage in their application
An integration that enables llms documentation to be generated that takes into account information about current best-practices and deprecations that is already contained within source code documentation would be ideal for helping to robustly solving this problem and helping guide LLM users towards using best practices.
What is the feature you are proposing to solve the problem?
I think there's two features this plugin requires to support a great story for api documentation
Channels would be configurable. For instance if an app configures two channels
modernandwith-legacythen four files would be produced:Transformers would be functions that take in a source file + a channel list and produce the a new "file" for each channel for the plugin to use.
In practice, how this would allow the problem to be solved:
Consider Typedoc, a leading solution for generating robust API documentation from source code, and which via its markdown plugin offers a quick integration with vitepress. Typedoc uses tsdoc/jsdoc tags (such as
@deprecated) to produce meta information and sections in the resulting markdown.A two channel configuration + transformer could check for the presence of
Deprecatedon items in the file and either remove them or keep them based on the channel.What alternatives have you considered?
No response