On Wed, Jun 19, 2019 at 12:30:26AM +0200, John Ogness wrote: > On 2019-06-18, Peter Zijlstra <pet...@infradead.org> wrote: > >> +/** > >> + * DOC: memory barriers > > > > What's up with that 'DOC' crap? > > The separate documentation in > Documentation/core-api/printk-ringbuffer.rst references this so it > automatically shows up in the kernel docs. An external reference > requires the DOC keyword. > > Maybe the memory barrier descriptions do not belong in the kernel docs?
So i'm biased; I don't much care for Documentation/ -- code should be readable and have sufficient comments; I hate rst and I think that anything that detracts from reading code comments in an editor is pure evil. Personally, I've stopped using /** comments, live is better now. YMMV > Sorry. I really have no feel about what (or how) exactly I should > document the memory barriers. I think the above comments make sense when > someone understands the details of the implementation. But perhaps it > should describe things such that someone without knowledge of the > implementation would understand what the memory barriers are for? That > would significantly increase the amount of text as I would have to > basically explain the implementation. > > I would appreciate it if you could point out a source file that > documents its memory barriers the way you would like to see these memory > barriers documented. Yeah, I was going to read the implementation and make suggestions; just haven't gotten there yet.
