[alsa-devel] [PATCH] ASoC: Fix kerneldoc errors

[Takashi Iwai]

At Mon, 10 Nov 2014 19:22:11 +0000,
Mark Brown wrote:
> 
> On Mon, Nov 10, 2014 at 08:09:45PM +0100, Takashi Iwai wrote:
> > Mark Brown wrote:
> 
> > > On Mon, Nov 10, 2014 at 05:30:45PM +0100, Takashi Iwai wrote:
> 
> > > > + * @list:   linked list of assigned pins to the same jack
> 
> > > I thought there was a way to mark implementation details that the user
> > > isn't supposed to look at as such in kerneldoc?
> 
> > You can put /* private: */ and /* public: */ comments.  See
> > Documentation/kernel-doc-nano-HOWTO.txt.
> 
> > But in this case, the list item appears as the first, so it'd become a
> > bit ugly.  Also, struct snd_soc_jack_zone has already the description
> > of list item, so having only one shown and one hidden would be
> > inconsistent.  For these reasons, I chose to add a comment on it,
> > too.
> 
> If we are going to do this sort of stuff and have people looking at the
> output I'd prefer that we did do those annotations (and move things
> around).  This just happened to be the first change in the diff but I'd
> guess there may be some other things that are undocumented because
> people aren't supposed to be looking at them (as well as ones that were
> just missed).

I don't mind in which ways.  Showing and hiding have both pros and
cons.  Please just fix your code before I pull for 3.19!


Takashi