question is related to Using Doxygen with C, do you comment the function prototype or the definition? Or both? .
doxygen formatting makes the declaration and its comments from my .h file appear first, followed by the definition and its comments from my .c file. good.
alas, is there some parameter like \param[in] or \return[in] that I can use just before the .c definition for the html output to indicate visually "now I am describing implementation"? It could put a boldface on the left, or even change the color to set it off visually. The obvious \implements tag does not do this.
I looked at the generated doxygen html code, and there is no obvious css class to change. so I presumably should use a tag from http://www.doxygen.nl/manual/commands.html . what do others use?
One option, which is not ideal but does have the merit of simplicity, is to use the \note command.
Prefixing the paragraphs describing the implementation with \note will result in them showing in the output with a green'y-yellow sidebar. You could change the color in the CSS. Subsequent \note paragraphs will remain as separate paragraphs but have a single heading and sidebar.
The downside is that the section is headed Note:. This may or may not be acceptable for your needs.
You could use \xrefitem instead, which would allow you to change the text to Implementation:, but it, quite reasonably, also generates an entry on a separate cross-reference page - which is probably not desirable. There may be a way of disabling the cross-indexing, but there's nothing in the manual about it.
I assume you are generating a document that is for internal use only; some form of Technical Manual perhaps? In which case, the 'Note' option may be the quickest and simplest solution.
Edit: I've just found the \remark command. Essentially equivalent to \note without a sidebar, but the associated heading Remarks may suit your application better. Chances are you can add the sidebar in the CSS.
Related
I have an OOM model with a few classes that will be transformed into C++ code.
I want certain sections (ie. custom #includes in .cpp files) to remain untouched when I re-generate the code from the model. However if I modify the model and generate the code again this defines & includes are lost.
Found nothing looking at the docs for macros or variables that may be of help.
Can anyone help?
In the Script tab of a class property sheet, there is a Imports subtab. Looking in the Object Language Definition, this attribute does not seem to be used anywhere.
I managed to use it by editing the Profile\Class\Templates\Source\includes_cpp template in the Language definition, adding %Imports% at the end.
After that, this Imports appears in the generated source:
#include "Class_2.h"
#include "Class_1.h"
MY INCLUDES
My editor is split into seperate "sections" eg
History
Examination
Results
Evaluation
which are edited seperately and different semantics (content type) affects functionality inside. Each section would be designated by Header (section title) and Content eg
History
...text here...
Examination
...text here...
The header has to be readonly so that it's content is not editable and header element itself can never be removed.
How would I implement this in draft.js?
A simple solution would be to use several draft instances. This does, however mean that they will have separate undo/redo stacks and copy/paste may not work as you expect.
The alternative solution would be to try to protect the headings, but it would require a lot of work, since you'd have to not only intercept when the user types normally, but also copy/paste and various other things.
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
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.
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.
I often find myself reading other developer's C code containing expressions like
ptr->member1.member2[i].another_member.final_member = 42;
and needing to find out what type final_member is. Usually what I do is to track down the chain of types using C tags, starting at the declaration of ptr and digging my way into the chain of members. This is cumbersome and often I'm stuck somewhere scratching my head, asking myself "What was the next member in the chain?" To make matters worse, a simple grep for final_member in the source tree turns up too many false positives due to the name being reused in more than one struct.
Is there a way to make vim give me the answer directly? I'm willing to install any plugin and even type a few characters while the cursor is on the final_member or select the whole expression :-) Non-GUI solutions preferred.
If i'm working on a project with several nested structs i add preview to the completeopt option.
In combination with the excellent omnicppcomplete plugin a tiny scratch window pops up if you select an entry in the completion menu. That scratch window shows some properties of the selected tag. Among other things it contains the search pattern for the tag which in case of a struct member usually contains its datatype.
I really suggest you to use plugin clang_complete (or some other plugin powered by clang) for completion. It will give you pure completion of C/C++/Objective-C code by real compiler, not ugly method by tags. Each item in completion menu also has type of field (that's what you are looking for)
Omnicppcomplete fails often on complicated expressions. Clang works great, since it is real awesome compiler.
Ui:include and xhtml based tag (the one with source elt) seem to be much the same for me. Both allow to reuse piece of markup. But I believe there should be some reason for having each. Could somebody please briefly explain it? (I guess if I read full facelets tutorial I will learn it, but I have not time to do it now, so no links to lengthy docs please :)
They are quite similar. The difference is mainly syntactical.
After observing their usage for some time it seems the convention is that fragments that you use only in a single situation are candidates for ui:include, while fragments that you re-use more often and have a more independent semantic are candidates for a custom tag.
E.g.
A single view might have a form with three sections; personal data, work history, preferences. If the page becomes unwieldy, you can divide it into smaller parts. Each of the 3 sections could be moved to their own Facelet file and will then be ui-include'ed into the original file.
On the other hand, you might have a specific way to display on image on many views in your application. Maybe you draw a line around it, have some text beneath it etc. Instead of repeating this over and over again you can abstract this to its own Facelet file again. Although you could ui:include it, most people seem to prefer to create a tag here, so you can use e.g. <my:image src="..." /> on your Facelets. This just looks nicer (more compact, more inline with other components).
In the Facelets version that's bundled with JSF 2.0, simple tags can be replaced by composite components. This is yet a third variant that on the first glance looks a lot like custom tags, but these things are technically different as they aren't merely an include but represent true components with declared attributes, ability to attach validators to, etc.