serde-rs
Consider unhiding `deserialize_in_place`
I was surprised to discover recently the existence of a hidden Deserialize::deserialize_in_place while reading the serde source code. In the docs it's explained:
This method is stable and an official public API, but hidden from the documentation because it is almost never what newbies are looking for. Showing it in rustdoc would cause it to be featured more prominently than it deserves.
While I can understand the urge to push people away from methods that are likely not what they need, I believe that this swings way too far in the other direction. Just today I answered a question on stack overflow from someone who was looking for exactly this functionality, and it's not clear to me how they ever would have discovered it, given that it's explicitly omitted from the rustdocs and doesn't appear to be mentioned in any other serde documentation.
Additionally, even if someone does know about it and use it in a project, their use would be confusing to anyone else reading the code, since they'd search serde and discover apparently that no such method exists.
Given these issues, and given that #[doc(hidden)] is fairly uniformly understood to be used for removing public items from the crate's public API (eg, for macro implementations, a pattern that serde itself makes extensive use of), I propose that #[doc(hidden)] be removed from this method, and it instead be simply documented as "likely not what you need." It could even be hidden instead behind a cargo feature flag to force users to opt into it.
Totally agree. Just found this after removing use of serde because I thought it didn't exist.
The correct way to indicate that this is not the method newbies are looking for is to state that in the documentation, not to exclude it from the documentation.
