lkml.org 
[lkml]   [2018]   [Jan]   [8]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH 02/18] Documentation: document nospec helpers
Hi Jon,

On Mon, Jan 08, 2018 at 09:29:17AM -0700, Jonathan Corbet wrote:
> On Fri, 05 Jan 2018 17:10:03 -0800
> Dan Williams <dan.j.williams@intel.com> wrote:
>
> > Document the rationale and usage of the new nospec*() helpers.
>
> I have just a couple of overall comments.
>
> - It would be nice if the document were done in RST and placed in the
> core-API manual, perhaps using kerneldoc comments for the macros
> themselves. It's already 99.9% RST now, so the changes required would
> be minimal.

Is there any quickstart guide to RST that you can recommend?

I'm happy to clean up the documentation; I'm just not familiar with RST.

> - More importantly: is there any way at all to give guidance to
> developers wondering *when* they should use these primitives? I think
> it would be easy to create a situation where they don't get used where
> they are really needed; meanwhile, there may well be a flood of
> "helpful" patches adding them where they make no sense at all.

This is on my TODO list.

The unfortunate truth is that it's likely to be a subjective judgement
call in many cases, depending on how likely it is that the user can
influence the code in question, so it's difficult to provide
hard-and-fast rules.

Thanks,
Mark.

\
 
 \ /
  Last update: 2018-01-14 23:17    [W:0.195 / U:0.684 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site