Re: [Doxygen-develop] PATCH limit warnings from doxygen

[<Pau...@am...>]

Dimitri

I hope you don't mind but I'm resending this to the develop list, this time with a smaller zip file as the previous one  bounced the email from the list and I am unsure if the list received the message.

The larger config.xml I removed, but outline the change needed here

-------------------------------------------------------
</docs>
    </option>
    <option type='int' id='LIMIT_WARNINGS' minval='0' maxval='10000' defval='0'>
      <docs>
<![CDATA[
The \c LIMIT_WARNINGS tag can be used to stop doxygen when a maximum number of warnings has been seen.
<br>
\b Tip: Turn warnings on while writing the documentation.
]]>
-------------------------------------------------------

Paul

From: Paul Hoad
Sent: 03 December 2014 12:57
To: 'dox...@li...'; 'di...@st...'
Subject: PATCH limit warnings from doxygen

Dimitri

I recently posted a question on StackOverFlow regarding being able to stop doxygen after it had seen a certain number of warnings, somewhat akin to the -ferror-limit=N option that certain compilers have.

http://stackoverflow.com/questions/27174031/possible-to-stop-doxygen-after-n-warnings

I have a large code base, mostly un-doxygen'd, I have a nightly build that runs doxygen but its produces thousands of warnings. I know getting full coverage is going to require a gradual continuous improvement approach which leads to a mindset change of the individual teams of developers.

So to tackle this I have added doxygen running on the current source subdirectory as "PreBuild Event" in Visual Studio project files, I don't want to use the temporary documentation it generates (that will come from the full tree nightly build), but I want to see the warnings, I format the warnings with

WARN_FORMAT            = "$file($line): $text"

Which this means that while the code is compiling, this allows the developer to go back in and double click the warnings in the output window and be taken to the location to fix those doxygen warnings (as they would any other warning), the problem is that for many of the directories the number of warnings is huge (which are too daunting to fix in one go)

I don't want to do a full Doxygen scan everytime (which is also why I only do it on the sub directory) because that will take too long and I don't want all the warnings or the developer will simply treat it a noise, I just want them to see a few and then stop.

My idea is to be able to tell doxygen to document locally only a certain number of warnings and then stop, this means that every build the developer will see a few more warnings (but only a couple 5-10) and be driven to fix those, over time the code will become documented and the developers will learn to document as they go, also any new code (especially in previously doxygen clean areas) will immediately become a warning. Think of it as "Continuous Incremental Documentation"

Given that I don't think this is possible currently, I took it upon myself to try and learn how to do it, I am very new to the doxygen source code, so I apologize in advance if I did it in the wrong place.

So the change to the doxygen source to implement something like this turned out to be fairly simple, with only having to add a new LIMIT_WARNINGS option to the config file, so I thought I would share the code change, feel free to use or discard as you see fit.

So I've not contributed before, so I'm not 100% clear of the etiquette or who to send any diffs to, so I've included the changed files and the diff from the tip of the git tree, if I should submit this another way, bug number etc.. let me know.

Paul

P.S. I couldn't find any requests like this in the bug tracker database.