[PATCH wayland 4/6] doc: Don't warn if something is undocumented

[Jonas Ådahl]

On Tue, Dec 29, 2015 at 05:31:33PM +0100, Nils Chr. Brause wrote:
> On 29 Dec 2015 3:20 pm, "Jonas Ådahl" <jadahl at gmail.com> wrote:
> >
> > On Tue, Dec 29, 2015 at 01:56:14PM +0100, Nils Chr. Brause wrote:
> > > No.
> > > If we want Wayland to be successful and widely used it has to be well
> > > documented (which it still is far from). Turning off warnings about
> > > undocumented fields doesn't exactly help the documentation effort but
> > > rather impedes it.
> > >
> >
> > There are a lot of these warnings, and I don't expect many of them to be
> > fixed because they are self explanatory non-public API which honestly
> > don't need any extra doxygen documentation. If you have ways to limit
> > these warnings to relevant parts (public API for example) I wouldn't
> > mind,
> 
> AFAIK, you can use EXCLUDE to exclude files, which only contain internal
> API and you can use \cond ... \endcond to exclude functions and structures
> inside a file.

That would not be good enough, since many of the doxygen documentation
are in the .c files and if we exclude those, we'd exclude most of the
documentation we actually care about.


Jonas

> 
> > but as they are now it's just hundreds of warnings to ignore
> > forever.
> >
> >
> > Jonas
> >
> > >
> > > On Tue, Dec 29, 2015 at 3:10 AM, Jonas Ådahl <jadahl at gmail.com> wrote:
> > > > There are lots of warnings about fields and other things not being
> > > > documented, and many of those will probably never be documented, so
> > > > stop warning about it.
> > > >
> > > > Signed-off-by: Jonas Ådahl <jadahl at gmail.com>
> > > > ---
> > > >  doc/doxygen/wayland.doxygen.in | 1 +
> > > >  1 file changed, 1 insertion(+)
> > > >
> > > > diff --git a/doc/doxygen/wayland.doxygen.in b/doc/doxygen/
> wayland.doxygen.in
> > > > index fb76b12..6cb77de 100644
> > > > --- a/doc/doxygen/wayland.doxygen.in
> > > > +++ b/doc/doxygen/wayland.doxygen.in
> > > > @@ -14,3 +14,4 @@ EXPAND_ONLY_PREDEF     = YES
> > > >  DOT_MULTI_TARGETS      = YES
> > > >  ALIASES                += comment{1}="/* \1 *<!-- -->/"
> > > >  GENERATE_HTML          = NO
> > > > +WARN_IF_UNDOCUMENTED   = NO
> > > > --
> > > > 2.4.3
> > > >
> > > > _______________________________________________
> > > > wayland-devel mailing list
> > > > wayland-devel at lists.freedesktop.org
> > > > http://lists.freedesktop.org/mailman/listinfo/wayland-devel