Re: statistics infrastructure (in -mm tree) review

Greg KH
2006-06-14T16:48:13Z

On Tue, Jun 13, 2006 at 05:18:27PM -0700, Randy.Dunlap wrote:
> On Tue, 13 Jun 2006 16:47:39 -0700 Greg KH wrote:
> > > +/**
> > > + * struct statistic_info - description of a class of statistics
> > > + * @name: pointer to name name string
> > > + * @x_unit: pointer to string describing unit of X of (X, Y) data pair
> > > + * @y_unit: pointer to string describing unit of Y of (X, Y) data pair
> > > + * @flags: only flag so far (distinction of incremental and other statistic)
> > > + * @defaults: pointer to string describing defaults setting for attributes
> > > + *
> > > + * Exploiters must setup an array of struct statistic_info for a
> > > + * corresponding array of struct statistic, which are then pointed to
> > > + * by struct statistic_interface.
> > > + *
> > > + * Struct statistic_info and all members and addressed strings must stay for
> > > + * the lifetime of corresponding statistics created with statistic_create().
> > > + *
> > > + * Except for the name string, all other members may be left blank.
> > > + * It would be nice of exploiters to fill it out completely, though.
> > > + */
> > > +struct statistic_info {
> > > +/* public: */
> > > + char *name;
> > > + char *x_unit;
> > > + char *y_unit;
> > > + int flags;
> > > + char *defaults;
> > > +};
> >
> > The whole "public:" and "private:" thing in these structures is not
> > needed. Just document it in the kernel-doc comments and you should be
> > fine. This isn't C++ :)
>
> but public: and private: are kernel-doc comments...
> Using "private:" causes those fields to be omitted from the
> generated documentation because those fields are for internal/private
> use of the (statistics) infrastructure code, not to be used by
> its clients (er, ugh, exploiters) etc.

Oh, I didn't realize that kerneldoc could do that now, nice. And look,
it's even documented that it can support that, I'll shut up now :)

thanks,

greg k-h