Re: [PATCH] Add TREAT_WARNINGS_AS_ERROR option
Albert <[email protected]> Sun, 6 Dec 2015 12:03:52 +0100
| Newsgroups | gmane.text.doxygen.devel |
|---|---|
| Message-ID | <CABOOx7af49_FN0LzBoBeV8pxgu5zbuu5dT0H--iMKCLkcxorPA@mail.gmail.com> |
--===============7539663287425457889== Content-Type: multipart/alternative; boundary=001a1134f27e25b425052638b215 --001a1134f27e25b425052638b215 Content-Type: text/plain; charset=UTF-8 In principle all the errors and warnings doxygen gives should be removed by the engineers. Doxygen distinguish between errors and warnings, where errors possibly corrupt the documentation building or are serious enough, in the eyes of the doxygen developers to stop the generation of the documentation. In case of an error the doxygen developer can also choose to give an error message but to continue anyway. When we would have the possibility to promote all the warnings to errors (and we should also stop at all errors that currently don't stop), it would mean that, when using the option, after each error a rerun is necessary. I think this is a bit overdone. I see some possibilities: - in case doxygen discovers warnings it does not finish with exit code 0 but with e.g. exit code 2 (and use exit code 1 for the errors on which it now already stops). - when using the proposed option the message is given as an error, but the process does not stop. I don't see this as an improvement as one can now catch the warnings in a log file and check them. - all warnings get a number and the user can "promote" in the Doxyfile some warnings to, fatal, errors. This would be quite a big effort as all the messages have to be categorized (I've been thinking about this some time ago, but have not started to implement this as it is a lot of work and does not bring enough in my opinion, a quick estimation 700 messages to be checked). The procedure I follow more or less is: Each time I'm building (overnight builds) the software I catch the warnings and errors in a warnings.log file. When this warnings.log file contains a message (or a new message compared to the last time the build was done) an email is send to the engineer who, last. changed the source file. Albert On Thu, Dec 3, 2015 at 9:34 PM, Gautier <[email protected]> wrote: > Hi list; > > As stated on Github[1], I would like to add an option behaving similarly > to compilers' -Werror option: any warning generated during Doxygen > execution will abort it immediately. > > This option is, in my opinion, valuable to keep documentation up-to-date > with code changes, specially when multiple people are working altogether. > I will not blame anyone to not think all consequence of a code change, > but scripts can help him/her from breaking anything: > > * strict compiler options (-Werror, -Wall, etc.) prevents at least some > quick&dirty code and obvious bugs. Compilers will warn beginners about > code which will not work (out of bounds errors, etc.), but most of the > time it's simply about a typo / useless dead code. > * Git hook preventing users from pushing invalid commits [2]. We are > intensively using git submodules for instance - it's quite easy to push > an invalid submodule reference to git: > * if you forgot to run "git submodule update --recursive" after > pulling remote changes following by a "git commit -a", leading to > unwilling submodule downgrading. > * if you're referencing a new submodule revision... which you > forgot to push first! > * To have better code consistency, following a single code style using > clang-format[3], similarly to what systemd does[4]. > > I think that all of us already encountered one or several of these > issues at least once ;-). Having tools checking these errors > automatically allow me not to worry about it anymore. > Our documentation contains nowadays many errors simply because Doxygen > let us do that and we did not look at """inoffensive""" warnings, since > they are not preventing us from continuing - they are lost in the > verbosity of build logs. > > I am the only one which would like such an option, and if so: how do you > keep your documentation up-to-date? > > Cheers, > > Gautier > > [1] https://github.com/doxygen/doxygen/pull/412 > [2] https://gist.github.com/bagage/bdca3d4b66d43db7a5e3 > [3] http://clang.llvm.org/docs/ClangFormat.html > [4] https://github.com/systemd/systemd/blob/master/autogen.sh > > > ------------------------------------------------------------------------------ > Go from Idea to Many App Stores Faster with Intel(R) XDK > Give your users amazing mobile app experiences with Intel(R) XDK. > Use one codebase in this all-in-one HTML5 development environment. > Design, debug & build mobile apps & 2D/3D high-impact games for multiple > OSs. > http://pubads.g.doubleclick.net/gampad/clk?id=254741911&iu=/4140 > _______________________________________________ > Doxygen-develop mailing list > [email protected] > https://lists.sourceforge.net/lists/listinfo/doxygen-develop > --001a1134f27e25b425052638b215 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable <div dir=3D"ltr"><div>In principle all the errors and warnings doxygen give= s should be removed by the engineers.<br><br>Doxygen distinguish between er= rors and warnings, where errors possibly corrupt the documentation building= or are serious enough, in the eyes of the doxygen developers to stop the g= eneration of the documentation. In case of an error the doxygen developer c= an also choose to give an error message but to continue anyway.<br><br>When= we would have the possibility to promote all the warnings to errors (and w= e should also stop at all errors that currently don't stop), it would m= ean that, when using the option, after each error a rerun is necessary. I t= hink this is a bit overdone.<br>I see some possibilities:<br>- in case doxy= gen discovers warnings it does not finish with exit code 0 but with e.g. ex= it code 2 (and use exit code 1 for the errors on which it now already stops= ).<br>- when using the proposed option the message is given as an error, bu= t the process does not stop. I don't see this as an improvement as one = can now catch the warnings in a log file and check them.<br>- all warnings = get a number and the user can "promote" in the Doxyfile some warn= ings to, fatal, errors. This would be quite a big effort as all the message= s have to be categorized (I've been thinking about this some time ago, = but have not started to implement this as it is a lot of work and does not = bring enough in my opinion, a quick estimation 700 messages to be checked).= <br><br>The procedure I follow more or less is: Each time I'm building = (overnight builds) the software I catch the warnings and errors in a warnin= gs.log file. When this warnings.log file contains a message (or a new messa= ge compared to the last time the build was done) an email is send to the en= gineer who, last. changed the source file.<br><br><br></div>Albert<br></div= ><div class=3D"gmail_extra"><br><div class=3D"gmail_quote">On Thu, Dec 3, 2= 015 at 9:34 PM, Gautier <span dir=3D"ltr"><<a href=3D"mailto:gautier@dam= sy.net" target=3D"_blank">[email protected]</a>></span> wrote:<br><block= quote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc= solid;padding-left:1ex">Hi list;<br> <br> As stated on Github[1], I would like to add an option behaving similarly<br= > to compilers' -Werror option: any warning generated during Doxygen<br> execution will abort it immediately.<br> <br> This option is, in my opinion, valuable to keep documentation up-to-date<br= > with code changes, specially when multiple people are working altogether.<b= r> I will not blame anyone to not think all consequence of a code change,<br> but scripts can help him/her from breaking anything:<br> <br> * strict compiler options (-Werror, -Wall, etc.) prevents at least some<br> quick&dirty code and obvious bugs. Compilers will warn beginners about<= br> code which will not work (out of bounds errors, etc.), but most of the<br> time it's simply about a typo / useless dead code.<br> * Git hook preventing users from pushing invalid commits [2]. We are<br> intensively using git submodules for instance - it's quite easy to push= <br> an invalid submodule reference to git:<br> =C2=A0 =C2=A0 =C2=A0* if you forgot to run "git submodule update --rec= ursive" after<br> pulling remote changes following by a "git commit -a", leading to= <br> unwilling submodule downgrading.<br> =C2=A0 =C2=A0 =C2=A0* if you're referencing a new submodule revision...= which you<br> forgot to push first!<br> * To have better code consistency, following a single code style using<br> clang-format[3], similarly to what systemd does[4].<br> <br> I think that all of us already encountered one or several of these<br> issues at least once ;-). Having tools checking these errors<br> automatically allow me not to worry about it anymore.<br> Our documentation contains nowadays many errors simply because Doxygen<br> let us do that and we did not look at """inoffensive"&q= uot;" warnings, since<br> they are not preventing us from continuing - they are lost in the<br> verbosity of build logs.<br> <br> I am the only one which would like such an option, and if so: how do you<br= > keep your documentation up-to-date?<br> <br> Cheers,<br> <br> Gautier<br> <br> [1] <a href=3D"https://github.com/doxygen/doxygen/pull/412" rel=3D"noreferr= er" target=3D"_blank">https://github.com/doxygen/doxygen/pull/412</a><br> [2] <a href=3D"https://gist.github.com/bagage/bdca3d4b66d43db7a5e3" rel=3D"= noreferrer" target=3D"_blank">https://gist.github.com/bagage/bdca3d4b66d43d= b7a5e3</a><br> [3] <a href=3D"http://clang.llvm.org/docs/ClangFormat.html" rel=3D"noreferr= er" target=3D"_blank">http://clang.llvm.org/docs/ClangFormat.html</a><br> [4] <a href=3D"https://github.com/systemd/systemd/blob/master/autogen.sh" r= el=3D"noreferrer" target=3D"_blank">https://github.com/systemd/systemd/blob= /master/autogen.sh</a><br> <br> ---------------------------------------------------------------------------= ---<br> Go from Idea to Many App Stores Faster with Intel(R) XDK<br> Give your users amazing mobile app experiences with Intel(R) XDK.<br> Use one codebase in this all-in-one HTML5 development environment.<br> Design, debug & build mobile apps & 2D/3D high-impact games for mul= tiple OSs.<br> <a href=3D"http://pubads.g.doubleclick.net/gampad/clk?id=3D254741911&iu= =3D/4140" rel=3D"noreferrer" target=3D"_blank">http://pubads.g.doubleclick.= net/gampad/clk?id=3D254741911&iu=3D/4140</a><br> _______________________________________________<br> Doxygen-develop mailing list<br> <a href=3D"mailto:[email protected]">Doxygen-develop@li= sts.sourceforge.net</a><br> <a href=3D"https://lists.sourceforge.net/lists/listinfo/doxygen-develop" re= l=3D"noreferrer" target=3D"_blank">https://lists.sourceforge.net/lists/list= info/doxygen-develop</a><br> </blockquote></div><br></div> --001a1134f27e25b425052638b215-- --===============7539663287425457889== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline ------------------------------------------------------------------------------ Go from Idea to Many App Stores Faster with Intel(R) XDK Give your users amazing mobile app experiences with Intel(R) XDK. Use one codebase in this all-in-one HTML5 development environment. Design, debug & build mobile apps & 2D/3D high-impact games for multiple OSs. http://pubads.g.doubleclick.net/gampad/clk?id=254741911&iu=/4140 --===============7539663287425457889== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ Doxygen-develop mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/doxygen-develop --===============7539663287425457889==--