[0/3] Clean up crypto documentation
mbox series

Message ID 156140322426.29777.8610751479936722967.stgit@taos
Headers show
Series
  • Clean up crypto documentation
Related show

Message

Gary R Hook June 24, 2019, 7:07 p.m. UTC
Tidy up the crypto documentation by filling in some variable
descriptions, make some grammatical corrections, and enhance
formatting.

---

Gary R Hook (3):
      crypto: doc - Add parameter documentation
      crypto: doc - Describe the crypto engine
      crypto: doc - Fix formatting of new crypto engine content


 Documentation/crypto/api-skcipher.rst  |    2 -
 Documentation/crypto/crypto_engine.rst |  120 ++++++++++++++++++++++----------
 Documentation/crypto/index.rst         |    1 
 include/linux/crypto.h                 |   11 +++
 4 files changed, 95 insertions(+), 39 deletions(-)

--

Comments

Joe Perches June 24, 2019, 7:30 p.m. UTC | #1
On Mon, 2019-06-24 at 19:07 +0000, Hook, Gary wrote:
> Tidy up the crypto documentation by filling in some variable
> descriptions, make some grammatical corrections, and enhance
> formatting.

While this seems generally OK, please try not to make the
readability of the source _text_ less intelligible just
to enhance the output formatting of the html.

e.g.:

Unnecessary blank lines separating function descriptions
Removing space alignment from bullet point descriptions

etc..,
Gary R Hook June 24, 2019, 8:06 p.m. UTC | #2
On 6/24/19 2:30 PM, Joe Perches wrote:
> On Mon, 2019-06-24 at 19:07 +0000, Hook, Gary wrote:
>> Tidy up the crypto documentation by filling in some variable
>> descriptions, make some grammatical corrections, and enhance
>> formatting.
> 
> While this seems generally OK, please try not to make the
> readability of the source _text_ less intelligible just
> to enhance the output formatting of the html.
> 
> e.g.:
> 
> Unnecessary blank lines separating function descriptions
> Removing space alignment from bullet point descriptions

Apologies. I generally consider white space a Good Thing,
but will take your note and not do that. The blank lines I
added do not affect the output, so I should not have done
that.

Also, I turned sentences into bulleted lists here, so I'm not
clear on whether that was a Bad Thing or not. Seems more legible
to me all the way around, but I clearly could be incorrect. I
agree that mucking with alignment is a bad thing, and would not
intentionally do so. That said, if you would please elaborate on
any mistakes I've made?

Finally, would you prefer a v2 of the patch set? Happy to do
whatever is preferred, of course.

grh
Joe Perches June 24, 2019, 8:29 p.m. UTC | #3
On Mon, 2019-06-24 at 20:06 +0000, Gary R Hook wrote:

Hi Gary.

> On 6/24/19 2:30 PM, Joe Perches wrote:
> > On Mon, 2019-06-24 at 19:07 +0000, Hook, Gary wrote:
> > > Tidy up the crypto documentation by filling in some variable
> > > descriptions, make some grammatical corrections, and enhance
> > > formatting.
> > 
> > While this seems generally OK, please try not to make the
> > readability of the source _text_ less intelligible just
> > to enhance the output formatting of the html.
> > 
> > e.g.:
> > 
> > Unnecessary blank lines separating function descriptions
> > Removing space alignment from bullet point descriptions
> 
> Apologies. I generally consider white space a Good Thing,
> but will take your note and not do that. The blank lines I
> added do not affect the output, so I should not have done
> that.
> 
> Also, I turned sentences into bulleted lists here, so I'm not
> clear on whether that was a Bad Thing or not.

To me, using bulleted lists are not a bad thing at all
but are quite the opposite for humans to read.

> Seems more legible
> to me all the way around, but I clearly could be incorrect.

Not at all.

> I agree that mucking with alignment is a bad thing, and would not
> intentionally do so. That said, if you would please elaborate on
> any mistakes I've made?
> 
> Finally, would you prefer a v2 of the patch set? Happy to do
> whatever is preferred, of course.

Whatever Jonathan decides is fine with me.
Mine was just a plea to avoid unnecessarily
making the source text harder to read as
that's what I mostly use.

I don't know if this extension is valid yet, but
I believe just using <function_name>() is more
readable as text than ``<function_name>`` or
:c:func:`<function_name>`

https://lore.kernel.org/lkml/20190425200125.12302-1-corbet@lwn.net/T/

I prefer the automatic approach over the manual
marking of functions as ideally sphinx formatting
should not overly impact the source text.
Jonathan Corbet June 24, 2019, 8:37 p.m. UTC | #4
On Mon, 24 Jun 2019 13:29:42 -0700
Joe Perches <joe@perches.com> wrote:

> > Finally, would you prefer a v2 of the patch set? Happy to do
> > whatever is preferred, of course.  
> 
> Whatever Jonathan decides is fine with me.
> Mine was just a plea to avoid unnecessarily
> making the source text harder to read as
> that's what I mostly use.

Usually Herbert seems to take crypto docs, so it's not necessarily up to
me :)

I don't see much that's objectionable here.  But...

> I don't know if this extension is valid yet, but
> I believe just using <function_name>() is more
> readable as text than ``<function_name>`` or
> :c:func:`<function_name>`

It's been "valid" since I wrote it...it's just not upstream yet :)  I
expect it to be in 5.3, though.  So the best way to refer to a kernel
function, going forward, is just function() with no markup needed.

Thanks,

jon
Joe Perches June 24, 2019, 10:37 p.m. UTC | #5
On Mon, 2019-06-24 at 14:37 -0600, Jonathan Corbet wrote:
> On Mon, 24 Jun 2019 13:29:42 -0700
> Joe Perches <joe@perches.com> wrote:
> 
> > > Finally, would you prefer a v2 of the patch set? Happy to do
> > > whatever is preferred, of course.  
> > 
> > Whatever Jonathan decides is fine with me.
> > Mine was just a plea to avoid unnecessarily
> > making the source text harder to read as
> > that's what I mostly use.
> 
> Usually Herbert seems to take crypto docs, so it's not necessarily up to
> me :)
> 
> I don't see much that's objectionable here.  But...
> 
> > I don't know if this extension is valid yet, but
> > I believe just using <function_name>() is more
> > readable as text than ``<function_name>`` or
> > :c:func:`<function_name>`
> 
> It's been "valid" since I wrote it...it's just not upstream yet :)  I
> expect it to be in 5.3, though.  So the best way to refer to a kernel
> function, going forward, is just function() with no markup needed.

When that's actually "valid" I suggest doing:

$ git ls-files -- 'Documentation/*.rst' | \
 xargs perl -pi -e 's/:c:func:`(\w+)(?:\(\))?`/\1()/g; s/``(\w+)\(\)``/\1()/g'

so function designations in Documentation are simpler to read.

Right now that's:

$ git diff --shortstat Documentation/
 125 files changed, 1680 insertions(+), 1680 deletions(-)
Gary R Hook June 25, 2019, 1:33 p.m. UTC | #6
On 6/24/19 3:37 PM, Jonathan Corbet wrote:
> On Mon, 24 Jun 2019 13:29:42 -0700
> Joe Perches <joe@perches.com> wrote:
> 
>>> Finally, would you prefer a v2 of the patch set? Happy to do
>>> whatever is preferred, of course.
>>
>> Whatever Jonathan decides is fine with me.
>> Mine was just a plea to avoid unnecessarily
>> making the source text harder to read as
>> that's what I mostly use.
> 
> Usually Herbert seems to take crypto docs, so it's not necessarily up to
> me :)
> 
> I don't see much that's objectionable here.  But...
> 
>> I don't know if this extension is valid yet, but
>> I believe just using <function_name>() is more
>> readable as text than ``<function_name>`` or
>> :c:func:`<function_name>`
> 
> It's been "valid" since I wrote it...it's just not upstream yet :)  I
> expect it to be in 5.3, though.  So the best way to refer to a kernel
> function, going forward, is just function() with no markup needed.

So I'm unclear:

1) would you prefer I wait on your 5.3 change being fully committed,
2) add your change to my local tree and use it, then submit an update 
patchset that depends upon it, or
3) re-submit now (using the current method) with suggested changes?

I'm thinking that this will go in after the referenced patch, so (2) is 
the preferred choice?

grh
Jonathan Corbet June 25, 2019, 1:52 p.m. UTC | #7
On Tue, 25 Jun 2019 13:33:27 +0000
Gary R Hook <ghook@amd.com> wrote:

> > It's been "valid" since I wrote it...it's just not upstream yet :)  I
> > expect it to be in 5.3, though.  So the best way to refer to a kernel
> > function, going forward, is just function() with no markup needed.  
> 
> So I'm unclear:
> 
> 1) would you prefer I wait on your 5.3 change being fully committed,
> 2) add your change to my local tree and use it, then submit an update 
> patchset that depends upon it, or
> 3) re-submit now (using the current method) with suggested changes?

I would just not mark up function() at all, and the right thing will
happen to it in the very near future.

Thanks,

jon
Gary R Hook June 25, 2019, 3:29 p.m. UTC | #8
On 6/25/19 8:52 AM, Jonathan Corbet wrote:
> On Tue, 25 Jun 2019 13:33:27 +0000
> Gary R Hook <ghook@amd.com> wrote:
> 
>>> It's been "valid" since I wrote it...it's just not upstream yet :)  I
>>> expect it to be in 5.3, though.  So the best way to refer to a kernel
>>> function, going forward, is just function() with no markup needed.
>>
>> So I'm unclear:
>>
>> 1) would you prefer I wait on your 5.3 change being fully committed,
>> 2) add your change to my local tree and use it, then submit an update
>> patchset that depends upon it, or
>> 3) re-submit now (using the current method) with suggested changes?
> 
> I would just not mark up function() at all, and the right thing will
> happen to it in the very near future.

Done.

I applied your two patches (locally) to verify the result, and it looks 
good to me. In the interim, I think it's NBD.

Thanks much.

grh