From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-15.7 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, MAILING_LIST_MULTI,MENTIONS_GIT_HOSTING,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id B2635C4338F for ; Mon, 26 Jul 2021 12:28:12 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 9463260241 for ; Mon, 26 Jul 2021 12:28:12 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233713AbhGZLrm (ORCPT ); Mon, 26 Jul 2021 07:47:42 -0400 Received: from smtp-out1.suse.de ([195.135.220.28]:55796 "EHLO smtp-out1.suse.de" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233959AbhGZLrm (ORCPT ); Mon, 26 Jul 2021 07:47:42 -0400 Received: from relay2.suse.de (relay2.suse.de [149.44.160.134]) by smtp-out1.suse.de (Postfix) with ESMTP id 4991F21F83; Mon, 26 Jul 2021 12:28:10 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.com; s=susede1; t=1627302490; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=QU8cYwdmsrvtBphYVUXeLz/ruYBbJBccan55c4kG70c=; b=Sc0PLAp+3Sctjax5ynY7A1H0jpBc86Kpsj08x6eojdXFJfYun/HMGGaj4tZ0+3ilvs3Wrw 9bRwT3c8yQePfD4PwylTdxLgyFr7VkOnIo/dhcaS9i/i0K0PTd8hfUgl7rGn5j2xGi3oKp oxlY0QKRsZklkfymDOPH+HndZrKo0as= Received: from suse.cz (unknown [10.100.224.162]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by relay2.suse.de (Postfix) with ESMTPS id D6FAEA3B8E; Mon, 26 Jul 2021 12:28:09 +0000 (UTC) Date: Mon, 26 Jul 2021 14:28:09 +0200 From: Petr Mladek To: Jonathan Corbet Cc: Chris Down , Stephen Rothwell , linux-doc@vger.kernel.org, Linux Kernel Mailing List , Linux Next Mailing List Subject: Re: linux-next: build warning after merge of the printk tree Message-ID: References: <20210720162423.75f61ce0@canb.auug.org.au> <87o8aqt7qn.fsf@meer.lwn.net> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <87o8aqt7qn.fsf@meer.lwn.net> Precedence: bulk List-ID: X-Mailing-List: linux-doc@vger.kernel.org On Sun 2021-07-25 15:16:00, Jonathan Corbet wrote: > Chris Down writes: > > > Chris Down writes: > >>+Cc: Jonathan Corbet , linux-doc@vger.kernel.org > > > > Well, let's actually Cc them this time... > > > >>Stephen Rothwell writes: > >>>After merging the printk tree, today's linux-next build (htmldocs) > >>>produced this warning: > >>> > >>>kernel/printk/printk.c:1: warning: 'printk' not found > >>> > >>>Introduced by commit > >>> > >>> 337015573718 ("printk: Userspace format indexing support") > >>> > >>>I presume that "printk" is referred to elsewhere in the documentation > >>>as being in this file. > >> > >>Hmm, this is an interesting one, because I think we still generally > >>just want to refer to the API as being `printk()`. Changing it all > >>over the place seems wrong. As you'd imagine, there are quite a few > >>references to this name, so it requires a lot of noise all over the > >>docs and inline comments. > >> > >>Jonathan and other docs folks, how can one tell Sphinx that when it > >>sees printk() it's referring to a function-like macro, or otherwise > >>squelch this reasonably? :-) > > The problem is that you moved printk(), but left the associated > kerneldoc comment tied to _printk(), which isn't what you really want to > document. The fix should look something like the attached. > > Thanks, > > jon > > --------snip here---------------------- > printk: Move the printk() kerneldoc comment to its new home > > Commit 337015573718 ("printk: Userspace format indexing support") turned > printk() into a macro, but left the kerneldoc comment for it with the (now) > _printk() function, resulting in this docs-build warning: > > kernel/printk/printk.c:1: warning: 'printk' not found > > Move the kerneldoc comment back next to the (now) macro it's meant to > describe and have the docs build find it there. > > Signed-off-by: Jonathan Corbet This looks better than my variant. I have pushed it into printk/linux.git, branch for-5.15-printk-index. Best Regards, Petr