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

Re: [PATCH v7 9/9] docs/doxygen: doxygen documentation for grant_table.h


  • To: Luca Fancellu <luca.fancellu@xxxxxxx>
  • From: Jan Beulich <jbeulich@xxxxxxxx>
  • Date: Mon, 5 Jul 2021 15:03:25 +0200
  • Arc-authentication-results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=suse.com; dmarc=pass action=none header.from=suse.com; dkim=pass header.d=suse.com; arc=none
  • Arc-message-signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=NNvUtbKDDtkudyr48bQpvmevEivU/ymo5pA72T+9QcI=; b=jamP7s0FgbbDq2lOmoEqO4ylv1ER6IMD9/6N2xeB6c5vZsQq/FcWbsA1+Lgfcpn3k6JvtExsxWdc5oAzbt3aaDOOal89+2yoR16uqdh24IJQfS+tdUUMLu3AqGD0AMQGENsMofxwY9+5i5EiwuNeqqzKXHR5jTL+RBI945He7Vutr6cTpAVYl6iFSxnwTn9lIza6KZJjvqpCThbzjZQKxUJhVWEMpCppb2Lh+oCos4kyedVG0Xfr5XjyI8AG1PeEI5TphGPZOwHApHshwEZYThkgvMVJHULsMLy+88SDXKAt9QBCKMOVwkmIvuM7eZ/Z/1iPFjJqym6tR4uGrV/qwQ==
  • Arc-seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=R8mAlu82qsJuSj9yVD8MdjEotKZvPuZdO65Vc/MUB3oNGByvMk4B2MocIA2laso87jUG/Jcewh5ji3MBq3xGR62f0J253q09S+bsBE3t91Lw/RNpp4QUpZckKdLpTJIwR+HJPEmUuNDWnx1ZSDUZH/pe5JJcMEkvQjaphBtI6gIznQ7wWU2dEj9k7O8E8wx3rsF9xNczDSO0ZycqwjV5IfLCU3CLfQA7vwlMri/5owJelAc5hwr43AjVijHKRBm54C06NApJ5NYCURvaO+i1Pg39G7qds2mIPqivGT34MQ32RcmHbO92rZnFG14U7cq6q6t/GuzgWCOCEoQskhBS3A==
  • Authentication-results: lists.xenproject.org; dkim=none (message not signed) header.d=none;lists.xenproject.org; dmarc=none action=none header.from=suse.com;
  • Cc: bertrand.marquis@xxxxxxx, wei.chen@xxxxxxx, Andrew Cooper <andrew.cooper3@xxxxxxxxxx>, George Dunlap <george.dunlap@xxxxxxxxxx>, Ian Jackson <iwj@xxxxxxxxxxxxxx>, Julien Grall <julien@xxxxxxx>, Stefano Stabellini <sstabellini@xxxxxxxxxx>, Wei Liu <wl@xxxxxxx>, xen-devel@xxxxxxxxxxxxxxxxxxxx
  • Delivery-date: Mon, 05 Jul 2021 13:03:34 +0000
  • List-id: Xen developer discussion <xen-devel.lists.xenproject.org>

On 05.07.2021 12:51, Luca Fancellu wrote:
> Modification to include/public/grant_table.h:
> 
> 1) Add doxygen tags to:
>  - Create Grant tables section
>  - include variables in the generated documentation
>  - Used @keepindent/@endkeepindent to enclose comment
>    section that are indented using spaces, to keep
>    the indentation.
> 2) Add .rst file for grant table
> 
> Signed-off-by: Luca Fancellu <luca.fancellu@xxxxxxx>
> ---
> v7 changes:
> - commit message changed
> - Add comment about grant table queries and uses
> to the documentation
> v6 changes:
> - Fix misaligned comment
> - Moved comments to make them display in the docs
> - Included more documentation in the docs
> v5 changes:
> - Move GNTCOPY_* define next to the flags field
> v4 changes:
> - Used @keepindent/@endkeepindent doxygen commands
>   to keep text with spaces indentation.
> - drop changes to grant_entry_v1 comment, it will
>   be changed and included in the docs in a future patch
> - Move docs .rst to "common" folder
> v3 changes:
> - removed tags to skip anonymous union/struct
> - moved back comment pointed out by Jan
> - moved down defines related to struct gnttab_copy
>   as pointed out by Jan
> v2 changes:
> - Revert back to anonymous union/struct
> - add doxygen tags to skip anonymous union/struct
> ---
>  docs/hypercall-interfaces/arm64.rst           |   1 +
>  .../common/grant_tables.rst                   |   9 +

In patch 8 you now add arm32.rst and x86.rst as well, so it's at
least odd that here you alter only one of the three. However, ...

> --- a/docs/hypercall-interfaces/arm64.rst
> +++ b/docs/hypercall-interfaces/arm64.rst
> @@ -8,6 +8,7 @@ Starting points
>  .. toctree::
>     :maxdepth: 2
>  
> +   common/grant_tables

... to me this seems the wrong way round anyway: I'd rather see
common stuff not be linked from per-arch locations, but per-arch
docs to be down the hierarchy from common ones.

Jan




 


Rackspace

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