Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Wed, 14 Jun 2023 10:38:52 -0700
From:   Jakub Kicinski <kuba@kernel.org>
To:     "Kubalewski, Arkadiusz" <arkadiusz.kubalewski@intel.com>
Cc:     "netdev@vger.kernel.org" <netdev@vger.kernel.org>,
        "linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>,
        "davem@davemloft.net" <davem@davemloft.net>,
        "pabeni@redhat.com" <pabeni@redhat.com>,
        "edumazet@google.com" <edumazet@google.com>,
        "chuck.lever@oracle.com" <chuck.lever@oracle.com>
Subject: Re: [PATCH net-next] tools: ynl-gen: generate docs for
 <name>_max/_mask enums
Message-ID: <20230614103852.3eb7fd02@kernel.org>
In-Reply-To: <DM6PR11MB46570AEF7E10089E70CC1D019B5AA@DM6PR11MB4657.namprd11.prod.outlook.com>
References: <20230613231709.150622-1-arkadiusz.kubalewski@intel.com>
        <20230613231709.150622-3-arkadiusz.kubalewski@intel.com>
        <20230613175928.4ea56833@kernel.org>
        <DM6PR11MB46570AEF7E10089E70CC1D019B5AA@DM6PR11MB4657.namprd11.prod.outlook.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Precedence: bulk

On Wed, 14 Jun 2023 12:48:14 +0000 Kubalewski, Arkadiusz wrote:
> >From: Jakub Kicinski <kuba@kernel.org>
> >Sent: Wednesday, June 14, 2023 2:59 AM
> >
> >On Wed, 14 Jun 2023 01:17:09 +0200 Arkadiusz Kubalewski wrote:  
> >> Including ynl generated uapi header files into source kerneldocs
> >> (rst files in Documentation/) produces warnings during documentation
> >> builds (i.e. make htmldocs)
> >>
> >> Prevent warnings by generating also description for enums where
> >> rander_max was selected.  
> >
> >Do you reckon that documenting the meta-values makes sense, or should
> >we throw a:
> >
> >/* private: */
> >  
> 
> Most probably it doesn't..
> Tried this:
> /*
>  [ other values description ]
>  * private:
>  * @__<NAME>_MAX
>  */
> and this:
> /*
>  [ other values description ]
>  * private: @__<NAME>_MAX
>  */
> 
> Both are not working as we would expect.
> 
> Do you mean to have double comments for enums? like:
> /*
>  [ other values description ]
>  */
> /*
>  * private:
>  * @__<NAME>_MAX
>  */
>
> >comment in front of them so that kdoc ignores them? Does user space
> >have any use for those? If we want to document them...
> 
> Hmm, do you recall where I can find proper format of such ignore enum comment
> for kdoc generation?
> Or maybe we need to also submit patch to some kdoc build process to actually
> change the current behavior?

It's explained in the kdoc documentation :(
https://docs.kernel.org/doc-guide/kernel-doc.html#members