Re: [PATCH v5] Documentation: test.h - fix warnings

From: Brendan Higgins <brendanhiggins@google.com>
To: Lothar Rubusch <l.rubusch@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>,
	KUnit Development <kunit-dev@googlegroups.com>,
	"open list:KERNEL SELFTEST FRAMEWORK" 
	<linux-kselftest@vger.kernel.org>
Subject: Re: [PATCH v5] Documentation: test.h - fix warnings
Date: Mon, 20 Apr 2020 09:49:18 -0700	[thread overview]
Message-ID: <CAFd5g47tOo2fQCc4GSFAist9b3pef0C6fYiV9bOf=sdfgAyd8g@mail.gmail.com> (raw)
In-Reply-To: <20200415201653.106-1-l.rubusch@gmail.com>

On Wed, Apr 15, 2020 at 1:18 PM Lothar Rubusch <l.rubusch@gmail.com> wrote:
>
> Fix warnings at 'make htmldocs', and formatting issues in the resulting
> documentation.
>
> - test.h: Fix annotation in kernel-doc parameter description.
>
> - Documentation/*.rst: Fixing formatting issues, and a duplicate label
>   issue due to usage of sphinx.ext.autosectionlabel and identical labels
>   within one document (sphinx warning)
>
> Signed-off-by: Lothar Rubusch <l.rubusch@gmail.com>

Reviewed-by: Brendan Higgins <brendanhiggins@google.com>

FYI: I already gave you a Reviewed-by. In the future, please add
Reviewed-bys you get to any follow-up patches. (You don't have to do
anything if you get a Reviewed-by and don't have to send follow-up
revisions.)

Let me know if you have any questions about how this works.

> ---
> v2: Several documentation fixes
>
> v3: Do not touch API documentation index
>
> v4: Replace macro argument in test.h by named variadic argument
>
> v5: Patch format fixed
>
> NB: checkpatch.pl will complain about flow control statements (i.e. usage
>     of "return") within the macro kunit_test_suites(suites_list...).

Yeah, it's a "bad code smell", but not necessarily always wrong, so
right now we don't have anything better than to just always warn and
sometimes ignore.

> Better?

Looks good to me!

> I feel I'm making you a lot of extra work. I'm really sorry for
> all this fuzz!

No worries. Our documentation/on-boarding processes are at best not
very good and at worst non-existent, so this is pretty much just par
for the course.

Thanks for sticking with this! I know getting up to speed on upstream
Linux kernel development can be painful and tedious. I have been there
myself, and I still make lots of silly mistakes. :-)

Sorry, if I ever seemed impatient: I am not annoyed. I respond to
dozens of emails everyday, so I can sometimes get rather terse as a
result of trying to be expedient. I hope you understand!

Trust me, once you go to a Linux conference and you meet some devs,
you will find that in person, most of us are super nice people, even
the ones who can *seem* mean and frustrated on the list.

Thanks for the patch! Hope to see you around in the community!