Document MISRA/QA-C message suppression with Doxygen

Question

I'm currently working on a project, which has to be MISRA 2012 compliant. But in the embedded world, you can't fulfill every MISRA rule. So I have to suppress some messages generated by QA-C. What's he best solution to do this?

I was thinking about making a table in every module header file with references (\ref and \anchor) to the relevant code lines, a description, etc. The first problem is: I can't use the Doxygen markdown table feature, because then the description has to be in one line, because Doxygen tables don't support line breaking. So I thought about using a simple verbatim table, what do you think?

Or is there a way to generate such a table automatically?

Greetings m0nKeY

Answer 1

According to MISRA, all such undesired rules must be handled by your deviation procedure, given that they are either "required" or "advisory". You are not allowed to deviate from "mandatory" rules. (Strictly speaking, you don't need to invoke the deviation procedure for advisory rules.)

In my experience, the safest and smoothest way by far to do this, is to not allow individual deviations on case-by-case basis. All deviations from MISRA should be stated in your company coding standard, and in order to deviate you have to update that document. Which in turn enforces approval from the document owner, who is preferably the most hardened C veteran you have in the team.

That way, you prevent less experienced team members from misinterpreting the rules and ignoring important rules, simply because they don't understand them and mistake them for false positives. There should be a rationale in the document stating why the rule you deviate from is not feasible for your company.

This means that everyone in the dev team is allowed to deviate from the listed rules at any point, without the need to invoke any form of bureaucracy.

Once you have a setup like this, simply customize your static analyser and remove/ignore the undesired warnings. That way, you get rid of a lot of noise and false warnings from the tool.

Answer 2

To answer your question generally: To create an aggregate occurrence list of anything in doxygen, use \xrefitem

We use this as a tool in our code review process. I tag code with a custom tag \reviewme which adds the function to a list of all code in need of peer review. The next guy can come along and clear that tag. We have another custom tag \reviewedby which does not use \xrefitem but simply puts the reivewers name and the date in the code block saying who reviewed it and when. This had gotten a bit clunky as things have scaled with larget code bases and more developers. Now we're looking into tools that integrate with our version control process to handle this better. But when we started this it worked well and fit a shoestring budget. But that example should give you an idea of is capable.

Here is a screen shot of what the output looks like - proprietary stuff and auto names redacted:

Here is how we added this custom tag as an alias to xrefitem in our doxy file as follows

ALIASES = "reviewme = \xrefitem reviewme \"This section needs peer review\" \"Documentation block or code sections that need peer review\""

To add it from the GUI, you would go to Expert->Project->Aliases and add a line like this

reviewme = \xrefitem reviewme "This section needs peer review" "Documentation block or code sections that need peer review"

Same thing, just no need to put quotes around the whole thing and escape out the inner quotes.

\xrefitem is the underpinning of how things like \todo or \bug work in doxygen. You can make a list of just about anything your heart desires.

Speaking specifically to MISRA exceptions: Lundin's post has lot's of merit. I would consider it. I think a better place to document exceptions to coding standards is in the static analysis tool its self. Many tools have their own annotations where you can categorize the rule violation as 'excused' or whatever. But generally this does not remove them from the list, it allows you just to filter or sort them. Perhaps you can use REGEX in a script that runs prior to doxygen that will replace the tool specific annotation with a custom \xrefitem if you are really concerned. Or vice vera, replace the doxy annotation with your tool's annotation.