On Mon, May 25, 2020 at 11:36:49AM +0200, Ahmed S. Darwish wrote: > Peter Zijlstra <peterz@xxxxxxxxxxxxx> wrote: > > I will not let sensible code comments deteriorate to the benefit of some > > external piece of crap. > > > > As a programmer the primary interface to all this is a text editor, not > > a web broswer or a pdf file or whatever other bullshit. > > > > If comments are unreadable in your text editor, they're useless. > > Wait. > > Most of the patch in question is just substituting the code snippet's > leading white spaces to tabs. For illustration purposes, if we remove > these white space hunks from the diff, it becomes: > > --- a/include/linux/seqlock.h > +++ b/include/linux/seqlock.h > @@ -232,6 +232,8 @@ static inline void raw_write_seqcount_end(seqcount_t *s) > + * .. code-block:: c > ... > + * .. code-block:: c > ... > - * NOTE: The non-requirement for atomic modifications does _NOT_ include > - * the publishing of new entries in the case where data is a dynamic > - * data structure. > + * .. attention:: > + * > + * The non-requirement for atomic modifications does _NOT_ include > + * the publishing of new entries in the case where data is a dynamic > + * data structure. > ... > > Are you trying to tell me that, good heavens, these directives are > really hurting your eyes so much? Yep, they're a distraction and serve absolutely no purpose. They're also utterly moronic, of course it's code and of course it's bloody well C. > Putting kernel-doc aside... That huge raw_write_seqcount_latch() comment > is actually *way more readable from any text editor* after applying this > patch. Go figure. I don't mind the re-indent. > >>> The correct fix is, as always, to remove the kernel-doc marker. > > Sorry, that's not the correct fix. Of course it is, if kerneldoc complains that a perfectly good comment is no good, then the fault lies with kerneldoc. It's like checkpatch; assume it is wrong :-) > In the following patches, kernel-doc for the entire seqlock.h API is > added. Singling out raw_write_seqcount_latch() doesn't make any sense. % s/\/\*\*/\/\*/g -- tada!! > If you look at the top of this patch series, a lot of seqlock.h > seqcount_t call sites were badly broken. The 0day kernel test bot sent > me even more erroneous call sites due to the added lockdep checks. This > is an extra argument for the added documentation: the existing one is > horrible. I've nothing against improving comments, I'm just saying that RST is absolute atrocious shite and has nothing to do with good comments. If sphinx doesn't like "NOTE:' when go teach it. > So, please, don't claim that the current situation is fine. It is not. I've never claimed that. My claim is that RST is shite and has no added value.
