[for,v24,3/3] x86/sgx: Remove a subordinate clause
diff mbox series

Message ID 20191104200141.5385-3-jarkko.sakkinen@linux.intel.com
State New
Headers show
Series
  • [for,v24,1/3] x86/sgx: Use GFP_KERNEL for allocations
Related show

Commit Message

Jarkko Sakkinen Nov. 4, 2019, 8:01 p.m. UTC
The subordinate clause of last sentence of the sgx_ioc_enclave_pages()
does not provide any insight not already provided. Thus, remove it.
Also, using "i.e." (and "e.g.") in the documentation should be
considered a bad practice because it leaves it open ended.

Signed-off-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
---
 arch/x86/kernel/cpu/sgx/ioctl.c | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

Comments

Sean Christopherson Nov. 4, 2019, 9:21 p.m. UTC | #1
On Mon, Nov 04, 2019 at 10:01:41PM +0200, Jarkko Sakkinen wrote:
> The subordinate clause of last sentence of the sgx_ioc_enclave_pages()
> does not provide any insight not already provided. Thus, remove it.

Isn't the whole point of the documentation to help the user understand
*how* to use the API, not simply state exactly what the code does?

> Also, using "i.e." (and "e.g.") in the documentation should be
> considered a bad practice because it leaves it open ended.

How does stating the practical effect of the semantics leave the docs open
ended?  The man pages for open[1], close[2], read[3], dlopen[4], etc...
all provide examples (usually with "for example" verbiage) to call out
common scenarios to help the reader understand the details, and close()
also uses "i.e." to clarify.

[1] http://man7.org/linux/man-pages/man2/open.2.html
[2] http://man7.org/linux/man-pages/man2/close.2.html
[3] http://man7.org/linux/man-pages/man2/read.2.html
[4] http://man7.org/linux/man-pages/man3/dlopen.3.html
 
> Signed-off-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
> ---
>  arch/x86/kernel/cpu/sgx/ioctl.c | 8 +++-----
>  1 file changed, 3 insertions(+), 5 deletions(-)
> 
> diff --git a/arch/x86/kernel/cpu/sgx/ioctl.c b/arch/x86/kernel/cpu/sgx/ioctl.c
> index 289af607f634..87b2fb62825a 100644
> --- a/arch/x86/kernel/cpu/sgx/ioctl.c
> +++ b/arch/x86/kernel/cpu/sgx/ioctl.c
> @@ -468,11 +468,9 @@ static int sgx_encl_add_page(struct sgx_encl *encl,
>   * @encl:       pointer to an enclave instance (via ioctl() file pointer)
>   * @arg:	a user pointer to a struct sgx_enclave_add_pages instance
>   *
> - * Add (EADD) one or more pages to an uninitialized enclave, and optionally
> - * extend (EEXTEND) the measurement with the contents of the page. The range of

Why are you dropping the reference to the ENCLS functions?  Yes, it's
stating the obvious for those of us that have been buried in SGX for the
last few years, but for newbies reading the docs I think there is value in
explicitly connecting the actions to the ENCLS function.

> - * pages must be virtually contiguous. The SECINFO and measurement mask are
> - * applied to all pages, i.e. pages with different properties must be added in
> - * separate calls.
> + * Add one or more pages to an uninitialized enclave, and optionally extend the
> + * measurement with the contents of the page. The address range of pages must
> + * be contiguous. The SECINFO and measurement mask are applied to all pages.

I like making it "address range", but I'd prefer to keep the "virtually"
qualifier.  Again, probably stating the obvious for many readers, but I
don't think it's ever harmful and I like the clarification it provides
without having to stop and consider the context.

>   *
>   * A SECINFO for a TCS is required to always contain zero permissions because
>   * CPU silently zeros them. Allowing anything else would cause a mismatch in
> -- 
> 2.20.1
>
Jarkko Sakkinen Nov. 4, 2019, 10:36 p.m. UTC | #2
On Mon, Nov 04, 2019 at 01:21:22PM -0800, Sean Christopherson wrote:
> On Mon, Nov 04, 2019 at 10:01:41PM +0200, Jarkko Sakkinen wrote:
> > The subordinate clause of last sentence of the sgx_ioc_enclave_pages()
> > does not provide any insight not already provided. Thus, remove it.
> 
> Isn't the whole point of the documentation to help the user understand
> *how* to use the API, not simply state exactly what the code does?

For kdoc it should explain in clear and concise way

That clause does not provide any help for that. It just repeats with
different vocabulary the exact same thing as was already said.

> > Also, using "i.e." (and "e.g.") in the documentation should be
> > considered a bad practice because it leaves it open ended.
> 
> How does stating the practical effect of the semantics leave the docs open
> ended?  The man pages for open[1], close[2], read[3], dlopen[4], etc...
> all provide examples (usually with "for example" verbiage) to call out
> common scenarios to help the reader understand the details, and close()
> also uses "i.e." to clarify.

I did not find the use of "i.e." or "e.g." from those. When they
introduce an example it is done in a more structured way, not as
a subordinate clause.

/Jarkko
Jarkko Sakkinen Nov. 4, 2019, 10:37 p.m. UTC | #3
On Tue, Nov 05, 2019 at 12:36:59AM +0200, Jarkko Sakkinen wrote:
> On Mon, Nov 04, 2019 at 01:21:22PM -0800, Sean Christopherson wrote:
> > On Mon, Nov 04, 2019 at 10:01:41PM +0200, Jarkko Sakkinen wrote:
> > > The subordinate clause of last sentence of the sgx_ioc_enclave_pages()
> > > does not provide any insight not already provided. Thus, remove it.
> > 
> > Isn't the whole point of the documentation to help the user understand
> > *how* to use the API, not simply state exactly what the code does?
> 
> For kdoc it should explain in clear and concise way

... what the function does.

/Jarkko

Patch
diff mbox series

diff --git a/arch/x86/kernel/cpu/sgx/ioctl.c b/arch/x86/kernel/cpu/sgx/ioctl.c
index 289af607f634..87b2fb62825a 100644
--- a/arch/x86/kernel/cpu/sgx/ioctl.c
+++ b/arch/x86/kernel/cpu/sgx/ioctl.c
@@ -468,11 +468,9 @@  static int sgx_encl_add_page(struct sgx_encl *encl,
  * @encl:       pointer to an enclave instance (via ioctl() file pointer)
  * @arg:	a user pointer to a struct sgx_enclave_add_pages instance
  *
- * Add (EADD) one or more pages to an uninitialized enclave, and optionally
- * extend (EEXTEND) the measurement with the contents of the page. The range of
- * pages must be virtually contiguous. The SECINFO and measurement mask are
- * applied to all pages, i.e. pages with different properties must be added in
- * separate calls.
+ * Add one or more pages to an uninitialized enclave, and optionally extend the
+ * measurement with the contents of the page. The address range of pages must
+ * be contiguous. The SECINFO and measurement mask are applied to all pages.
  *
  * A SECINFO for a TCS is required to always contain zero permissions because
  * CPU silently zeros them. Allowing anything else would cause a mismatch in