Re: [PATCH v4 01/24] Documentation: locking: Describe seqlock design and usage

Steven Rostedt
2020-07-21T01:51:19Z

On Mon, 20 Jul 2020 21:44:00 -0400
Steven Rostedt <rostedt@goodmis.org> wrote:

> > - * This is not as cache friendly as brlock. Also, this may not work well
> > - * for data that contains pointers, because any writer could
> > - * invalidate a pointer that a reader was following.
> > + * See Documentation/locking/seqlock.rst
>
> I absolutely hate it when I see this.
>
> I much rather have the documentation next to the code. Because
> honestly, I trust that comments next to the code will get updated if
> the code changes much more likely than comments buried in the
> Documentation directory.
>
> It's also more likely that I wont even bother looking at the doc
> (because I wont trust it to be up to date) and just read the code and
> try to figure it out. Or look at how others have used it.

Never mind,

I see that kerneldoc is added in patch 5, which helps.

-- Steve