[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [PATCH] xen/iocap.h: add documentation


  • To: Grygorii Strashko <grygorii_strashko@xxxxxxxx>, Grygorii Strashko <gragst.linux@xxxxxxxxx>
  • From: Jan Beulich <jbeulich@xxxxxxxx>
  • Date: Tue, 11 Mar 2025 18:01:02 +0100
  • Autocrypt: addr=jbeulich@xxxxxxxx; keydata= xsDiBFk3nEQRBADAEaSw6zC/EJkiwGPXbWtPxl2xCdSoeepS07jW8UgcHNurfHvUzogEq5xk hu507c3BarVjyWCJOylMNR98Yd8VqD9UfmX0Hb8/BrA+Hl6/DB/eqGptrf4BSRwcZQM32aZK 7Pj2XbGWIUrZrd70x1eAP9QE3P79Y2oLrsCgbZJfEwCgvz9JjGmQqQkRiTVzlZVCJYcyGGsD /0tbFCzD2h20ahe8rC1gbb3K3qk+LpBtvjBu1RY9drYk0NymiGbJWZgab6t1jM7sk2vuf0Py O9Hf9XBmK0uE9IgMaiCpc32XV9oASz6UJebwkX+zF2jG5I1BfnO9g7KlotcA/v5ClMjgo6Gl MDY4HxoSRu3i1cqqSDtVlt+AOVBJBACrZcnHAUSuCXBPy0jOlBhxPqRWv6ND4c9PH1xjQ3NP nxJuMBS8rnNg22uyfAgmBKNLpLgAGVRMZGaGoJObGf72s6TeIqKJo/LtggAS9qAUiuKVnygo 3wjfkS9A3DRO+SpU7JqWdsveeIQyeyEJ/8PTowmSQLakF+3fote9ybzd880fSmFuIEJldWxp Y2ggPGpiZXVsaWNoQHN1c2UuY29tPsJgBBMRAgAgBQJZN5xEAhsDBgsJCAcDAgQVAggDBBYC AwECHgECF4AACgkQoDSui/t3IH4J+wCfQ5jHdEjCRHj23O/5ttg9r9OIruwAn3103WUITZee e7Sbg12UgcQ5lv7SzsFNBFk3nEQQCACCuTjCjFOUdi5Nm244F+78kLghRcin/awv+IrTcIWF hUpSs1Y91iQQ7KItirz5uwCPlwejSJDQJLIS+QtJHaXDXeV6NI0Uef1hP20+y8qydDiVkv6l IreXjTb7DvksRgJNvCkWtYnlS3mYvQ9NzS9PhyALWbXnH6sIJd2O9lKS1Mrfq+y0IXCP10eS FFGg+Av3IQeFatkJAyju0PPthyTqxSI4lZYuJVPknzgaeuJv/2NccrPvmeDg6Coe7ZIeQ8Yj t0ARxu2xytAkkLCel1Lz1WLmwLstV30g80nkgZf/wr+/BXJW/oIvRlonUkxv+IbBM3dX2OV8 AmRv1ySWPTP7AAMFB/9PQK/VtlNUJvg8GXj9ootzrteGfVZVVT4XBJkfwBcpC/XcPzldjv+3 HYudvpdNK3lLujXeA5fLOH+Z/G9WBc5pFVSMocI71I8bT8lIAzreg0WvkWg5V2WZsUMlnDL9 mpwIGFhlbM3gfDMs7MPMu8YQRFVdUvtSpaAs8OFfGQ0ia3LGZcjA6Ik2+xcqscEJzNH+qh8V m5jjp28yZgaqTaRbg3M/+MTbMpicpZuqF4rnB0AQD12/3BNWDR6bmh+EkYSMcEIpQmBM51qM EKYTQGybRCjpnKHGOxG0rfFY1085mBDZCH5Kx0cl0HVJuQKC+dV2ZY5AqjcKwAxpE75MLFkr wkkEGBECAAkFAlk3nEQCGwwACgkQoDSui/t3IH7nnwCfcJWUDUFKdCsBH/E5d+0ZnMQi+G0A nAuWpQkjM1ASeQwSHEeAWPgskBQL
  • Cc: Stefano Stabellini <sstabellini@xxxxxxxxxx>, Julien Grall <julien@xxxxxxx>, Andrew Cooper <andrew.cooper3@xxxxxxxxxx>, Michal Orzel <michal.orzel@xxxxxxx>, Roger Pau Monne <roger.pau@xxxxxxxxxx>, Anthony PERARD <anthony.perard@xxxxxxxxxx>, xen-devel@xxxxxxxxxxxxxxxxxxxx
  • Delivery-date: Tue, 11 Mar 2025 17:01:27 +0000
  • List-id: Xen developer discussion <xen-devel.lists.xenproject.org>

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_strashko@xxxxxxxx>
>>>>
>>>> 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



 


Rackspace

Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.