On 11.03.2025 17:11, Grygorii Strashko wrote: > > Hi Jan, > > On 11.03.25 17:35, Jan Beulich wrote: >> On 11.03.2025 15:53, Grygorii Strashko wrote: >>> On 05.03.25 12:37, Jan Beulich wrote: >>>> On 24.02.2025 12:38, Grygorii Strashko wrote: >>>>> Change rangeset parameters to "start, last" as proposed in [1], >>>>> and add documentation for public interface. >>>>> >>>>> No functional changes. >>>>> >>>>> [1] https://patchwork.kernel.org/comment/26251962/ >>>>> Signed-off-by: Grygorii Strashko <grygorii_stras...@epam.com> >>>> >>>> To be honest, this is getting too verbose for my taste. I also don't think >>>> title and description fit together: One says the main thing the patch does >>>> is add doc, the other says the main thing is the parameter renaming. When >>>> then there's at least one further parameter which is also renamed, despite >>>> not fitting the description. >>> >>> I can update subject and commit message and resend. >> >> This would address the latter part of my comment, but ... >> >>> Or you want me to drop some parts? >> >> ... only this would address the former part. > > I'm very sorry, but I feel very much confused about your above comment :( > > So I'd be appreciated if You can provide some clarification here. > > 1) you do not want API documentation at all? > 2) you want API documentation, but only for some API? > 3) you are not satisfied with documentation style? > > In case 3, how do you want it to be look like? Could you point on any .h or > function in Xen, > to inherit the doc style? > > Here I've followed doxygen style (like in xen/include/xen/vmap.h for example) > Before proceeding I've checked CODING_STYLE and other headers as well and saw > that > there is no generic style for code documentation.
As said, my take is that this ends up too verbose. Personally I'm happy without any doc for these relatively simple interfaces. I could live with something lightweight. And if other maintainers think having this kind of extensive doc is useful, I also wouldn't veto this going in. But in the current shape I don#t think I'm willing to ack it. Jan
