-
-
Notifications
You must be signed in to change notification settings - Fork 1.5k
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
nim doc
recursive should allow doc generation only for public proc.
#14375
Comments
how do you distinguish whether an exported symbol is internal only? |
It's exported/reexported from the main file that end user import. |
personally I prefer more doc than less doc, as soon enough you need to read docs for internal procs when things go wrong or you need to customize or understand implementation, so if this feature is introduced and ppl start using it may actually hurt more. You already get almost what you want: eg, for https://github.com/nitely/nim-regex,
So you could inline those re-exported symbols in the main project html file, but then those symbols might depend on other private symbols in their definition, so you'd get incomplete information: eg: Also, inlining exported symbols would mean that you'd end up inlining a lot of symbols in case some of those re-exports are modules. That being said, I'd be ok with following: proposal
and finally, for non-open source projects that want their internal docs not shown (seems like a valid use case), an option |
My two cents, in libp2p we have a lot of exported-but-not-public procedures (probably 70% of our procedures actually) The big difference between and exported and a public procedure is that we don't necessarily keep backward compatibility for it. (we have to export it for our internal usage) A solution I found is to add a See here: vacp2p/nim-libp2p#650 I like this approach, because in the code you can see which procedures you should not break at a glance (vs hacking to check if they are re-exported somewhere else), and same for someone wanting to use the library, it's easy to know if you're supposed to use something or not. Though currently it relies on an ugly nim doc hack that I would like to improve |
Is there any consensus here? I did a prototype yesterday of the opposite of what @Menduist proposed. Basically, instead of ‘.public.’ it implements ‘.nodoc.’, but that could easily be flipped around and put behind a flag. I do agree that a “flattened” doc file that merged all re-exported files would be a better user experience, though. But also, maybe both mechanisms could work better together? |
@Nycto do you have your prototype available somewhere? It seems that everyone wants something different, maybe it should be customizable after all |
Yeah, absolutely. Here is my change: Nycto@ef3f3c7 I'm unclear if there are any unit tests for this code, so I haven't bundled it as a pull request yet. |
Currently using the nim doc for the global project via
will recursively generate doc for each Nim file of the project.
However, projects may have public procs that are internal only and public procs that are actually exposed to the users.
Currently there is no way to only keep those procs.
The text was updated successfully, but these errors were encountered: