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

[Nils Chr. Brause]

On 30 Dec 2015 01:24, "Jonas Ådahl" <jadahl at gmail.com> wrote:
>
> 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.

As said above, you can use \cond ... \endcond in those cases to just
exclude the parts, that are non-public API and should not be documented.

>
>
> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20151230/f9a6a13a/attachment.html>