[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

Hi Luca,

On 06/07/2021 09:44, Luca Fancellu wrote:

On 5 Jul 2021, at 15:20, Julien Grall <julien@xxxxxxx> wrote:

Hi Luca,

On 05/07/2021 11: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 +
  docs/xen-doxygen/doxy_input.list              |   1 +
  xen/include/public/grant_table.h              | 459 +++++++++++-------
  4 files changed, 288 insertions(+), 182 deletions(-)
  create mode 100644 docs/hypercall-interfaces/common/grant_tables.rst
diff --git a/docs/hypercall-interfaces/arm64.rst 
index 5e701a2adc..cb4c0d13de 100644
--- a/docs/hypercall-interfaces/arm64.rst
+++ b/docs/hypercall-interfaces/arm64.rst
@@ -8,6 +8,7 @@ Starting points
  .. toctree::
     :maxdepth: 2
  +   common/grant_tables
diff --git a/docs/hypercall-interfaces/common/grant_tables.rst 
new file mode 100644
index 0000000000..b8a1ef8759
--- /dev/null
+++ b/docs/hypercall-interfaces/common/grant_tables.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+Grant Tables
+.. doxygengroup:: grant_table
+   :project: Xen
+   :members:
+   :undoc-members:
diff --git a/docs/xen-doxygen/doxy_input.list b/docs/xen-doxygen/doxy_input.list
index e69de29bb2..233d692fa7 100644
--- a/docs/xen-doxygen/doxy_input.list
+++ b/docs/xen-doxygen/doxy_input.list
@@ -0,0 +1 @@
diff --git a/xen/include/public/grant_table.h b/xen/include/public/grant_table.h
index 84b1d26b36..2f826c952d 100644
--- a/xen/include/public/grant_table.h
+++ b/xen/include/public/grant_table.h
@@ -25,15 +25,19 @@
   * Copyright (c) 2004, K A Fraser
+ * @file
+ * @brief Interface for granting foreign access to page frames, and receiving
+ * page-ownership transfers.
+ */
    #include "xen.h"
- * `incontents 150 gnttab Grant Tables

Hi Julien,

`incontents is used by the script xen-headers to generate I believe [1].

Looking through the commit messages, I can't find any suggestion that the 
existing documentation has been retired or else. So can you clarify what's the 

If the plan to move to doxygen, then I think that
  1) the commit message or cover letter ought to explain why this is better 
than the current documentation
  2) you should remove xen-headers or outline the plan to do that. Note that 
after this series, I believe the bits for the grant table would end up to be 

Yes you are right, maybe it’s better to have a future serie that can reproduce 
and substitute the actual documentation.

I am actually not in favor of keeping two way to output the documentation.

What I am after is some clarification and plan so we don't end up to release 4.16 with half of the hypercalls described in doxygen and the other in the existing documentation.


Julien Grall



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