-
-
Notifications
You must be signed in to change notification settings - Fork 1.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add doc gen flags for lib, private, and all #14816
base: master
Are you sure you want to change the base?
Add doc gen flags for lib, private, and all #14816
Conversation
Parse/add docs for TypeDef/CStruct/Lib
This is meant more for the index.json output providing an overview of the methods available on each object
One area this doesn't cover is |
This looks like a good idea. However, I think this topic needs more in-depth analysis and exploration of different angles before going for a solution. Of course, it's tempting to just go with this as it's already implemented (and relatively simple). So it could be easily available. |
Trying to put together an RFC, but I'm not sure there's enough here to warrant it, as this is a minor improvement upon what currently exists. I'm also not sure what further exploration there could be into this subject, or what part of this could be non-ideal in the future that also wouldn't apply to the docs generator itself as a whole. This PR would enable more documentation for C bindings, and allow people to generate documentation for everything in their projects. It would also allow me to create a better development experience in VS Code. By having the entire top-level semantic, I can add better autocomplete/hover documentation/jump to definition, maybe even for static methods too, without the need to use an LSP. Do you have any examples in mind of what details and use cases this misses that couldn't be fixed in future PRs? In my mind, this discussion and development belongs in #6947 (which should be turned into an RFC), independent of this PR. |
@straight-shoota If I were to create a separate PR just adding support for generating documentation for C bindings (lib/fun/type/enum/etc), would that be accepted? That part is somewhat separate from the discussion about getting all semantic information from the compiler, and the RFC I'm trying to put together for that. |
Hm, this subset would certainly be easier to merge. However, I'd think it would be best to include the handling of lib types into the bigger discussion. |
If possible could you direct where that discussion should happen? I am very invested in getting this change through, it greatly helps me as a C binding author, and I would love to show this PR some support. |
As mentioned in #14816 (comment), the RFC repo https://github.com/crystal-lang/rfcs would be an ideal place for discussing a concrete proposal. Maybe before that we could collect some general ideas in a forum thread. |
This pull request has been mentioned on Crystal Forum. There might be relevant details there: https://forum.crystal-lang.org/t/extending-api-docs-and-compiler-semantic-output/7314/1 |
crystal tool hierarchy
#14711Three new flags are added to the documentation generator:
--include-all
will include everything in the namespace (stdlib, shards, project files)--include-private
will include all private methods--include-lib
will generate documentation for lib/fun/cstruct/union/typedef/etc