On Tue, Sep 3, 2024 at 9:47 PM Dmitry Torokhov <dmitry.torokhov@xxxxxxxxx> wrote: > > I was talking in general, not about this exact case, sorry if I was > unclear. But in general I personally have this issue with Rust and to > extent also with C++ where I constantly wonder if my code is "idiomatic > enough" or if it looks obsolete because it is "only" C++14 and not 17 > or 20. > > With C usually have no such concerns which allows me to concentrate on > different things. Yeah, I see the concern, and I agree that C++ later standards can be quite daunting to keep up with (and especially to learn new pitfalls around UB in new features, e.g. C++ ranges). With Rust, I think it is not that bad, at least so far and especially for minor features -- generally they are well thought-out and fairly regular, and at least for safe code the UB worry is not there, so it is easier to feel confident in using them. There are some major features, like `async`, that we may need to carefully consider indeed though. > I think exposing documentation for private function that can change at > any time and is not callable from outside has little value. That does > not mean that comments annotating such function have no value. But they > need to be taken together with the function code, and in this case > Alexey's concern about comments like "this increments that by 1" > becomes quite valid. To be clear, we are not exposing the documentation in the rendered form for private items. It is possible to do so though, but we don't enable that at the time being. Although I think it would be valuable to have a "toggle" to show it. I mean, sure, for private trivial functions, it may make not much sense to add due to the burden of writing and maintaining it. That is why we don't require documentation on private items so far, but we may want to nevertheless in the future for particular core APIs (so we could enable it in certain crates, for instance). Thanks for taking a look, by the way. Cheers, Miguel
