I have multiple assemblies for a library that I merge into a single assembly with ILmerge, using the /internalize flag. Additionally I also merge the xml docs generated by the compiler into a file using the /xmldocs.
The following question may sound bizarre but there is a reason behind:
Is there a way to remove the internalized methods documentation from the documentation xml?
Why? Because in a second step, I obfuscate the merged assembly. All internal methods are going to be renamed/modified and the documentation is therefore useless and even worse: it does reveal information about the obfuscated part.
Related
I'd like to use the PlantUML syntax to define component structures, which I want to process in an own tool. However, I'd like to avoid having to write a PlantUML parser. Is there some sort of intermediate representation in PlantUML, which I could use for that? It would be perfect to have e.g. a JSON structure which contains all diagram objects and relations among them in a concise way.
I could not find anything in the docs, maybe someone with more insights in the project can help?
As Jean-Marc Volle pointed out, the project github.com/jupe/puml2code allows to process puml files and generate source code in different languages using handlebar templates. Currently the code generation is limited to classes in a puml file.
I have used puml2code as a starting point for a new project github.com/robbito/puml2json, which simplifies the process a bit, as it doesn't require handlebar. Json ist directly generated from the PlantUML code. puml2json currenlty also only supports a subset of PlantUML.
Is there a such thing as a preprocessor whose statements, once processed, disappear completely and get replaced by the target language syntax permanently?
I want to research it on the web but I don't know what term to search for. If I search for "code generator", "templating language", "preprocessor directives", "mixins", "annotations" I get generators whose input becomes the source of truth.
The closest thing I can think of is a macro.
What I'm trying to do
I often have to write code that is verbose and unnecessary manual labor and am looking for a smarter way to input at least the majority of it and have it automatically transformed and only source-control the output (and hand edit if necessary). For example:
Java code - Instead of writing getters/setters, javadoc (perhaps the transformer can be a maven plugin)
HTML - I just want to add URLs, and have my preprocessor automatically convert them to links, images, videos, audio etc. depending on the file extension with some regex substitution (currently I run a perl script via a cron job)
I just want to use it as my own shorthand and not enforce it in my project and make the output editable so that others have to learn a new framework or language (like Protobuf, Stringtemplate, GWT, C hash-defines, PHP, JSP etc).
There should be no direct clue that I used a template/preprocessor to generate it.
What you want is a "program transformation system". See https://en.wikipedia.org/wiki/Program_transformation. (This is a superset of "transpilers" [ugly term]).
A good source-to-source transformation system will let you apply rewrite rules of the form of:
if you see *this*, replace it by *that* if *this_condition*.
You can then take your source code, and run a set of rewrite rules across that code to change it.
The resulting code is "transformed"; the rewrite rules are not visible.
It seems like Transpiler is one way to describe it.
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 have a code library that makes heavy use of XPathNavigator to parse some specific xml document. The xml document is cross-referenced, meaning that an element can reference another which has not yet been encountered during parsing:
<ElementA ...>
<DependentElementX id="1234">
</ElementA>
<ElementX id="1234" .../>
The document doesn't really look like this, but the point is that 1) there is an xml schema that enforces the overall document structure, 2) elements inside the document can reference each other using some IDs, and 3) there is quite a few such cross references between different elements in the document.
The document is parsed in two phases. In the first pass I walk through the document
XPathDocument doc = ...;
XPathNavigator nav = doc.CreateNavigator();
nav.MoveToRoot();
nav.MoveToFirstChild()...
and occasionally 'bookmark' the current position (element) in the document using XPathNavigator.Clone() method. This gives me a lightweight instance of an XPathNavigator which I can store somewhere and use later to jump back to a particular place (element) in my document.
Once I have enough information collected in the first pass (for example, I have made sure there is indeed an ElementX with an id='1234'), I jump back to saved bookmarks (using those saved XPathNavigators) and complete the parsing.
Well, now I'm about to use this library in Silverlight 3.0 and to my horror the XPathNavigator is not in the System.Xml assembly.
Questions:
1) Am I missing something obvious (i.e. XPathNavigator does exist in some shape or form, for example in a toolkit or a freeware library)?
2) If I do have to make modifications in the code, what would be the best way to go? Ideally, I would like to make minimal changes, not to rewrite 80% of the code just to be able to use something like XLinq.
To resume, in case I have to give up XPathNavigator, all I need is a way to bookmark places in my document and to get back to them so that I can continue to iterate from where I left off.
Thanks in advance for any help/ideas.
You are not missing something obvious, there is no implementation of XPathNavigator or XPathDocument in the Silverlight versions of the libraries.
The "best way to go" is highly subjective and would really depend on how many lines of code are really depending on XPathNavigator. However I see a couple of choices.
Go ahead and re-write the code using XDocument, XElement etc from the System.Xml.Linq namepsace. This may not be as bad a choice as you might think.
Wrap Xml-to-Linq objects in your own implementation of those properties and methods of the XPathNavigator that you are actually using. It shouldn't be too hard re-create most the features of the XPathNavigator against the Xml-to-Linq objects. You can then run your existing code against your own XPathNavigator.
XPath (xdoc.XPathSelectElements) is available in Silverlight 4: here's an online test tool.
There are tons of ways:
How to deal with XML in C#
You can still use Linq to XML just minus the linq syntax and use the Linq Extension methods.
We're trying to learn to use T4 Templates. I have a desire to use the System.Data.Entity.Design.PluralizationServices library in order to better pluralize some Entity Model names within my template, but I've come across some issues in the achievement of this goal.
Running code to generate output text. I think this is possible, but if it's not going to work, then there's no need to go any further. (I could call Date.Now.ToString() and get the expected result. I haven't tried anything much more complicated yet)
I am in a Silverlight App, and so I can't add a reference to the project for the PluralizationServices library in the place where I need the generated .cs file. I was planning on just moving the .tt file to a non-SL app, using the namespace and moving the generated file to the correct space. Haven't got that far yet, so I don't know how much trouble that will be, but it doesn't seem like it should be too hard.
My current problem is that when I import the namespace of the library, I get an "ErrorGeneratingOutput" and I haven't been able to move on past that yet.
I am having a hard time finding information about how the import command works, so I assume that it's just obvious. At the same time though, this one doesn't work so I wonder if it might be an exception to the standard.
<##import namespace="System.Data.Entity.Design.PluralizationServices" #>
I have no idea why adding this line (and only this line) causes everything to break. I haven't even started to try to use it yet! Is there something somewhere about libraries in T4 that I should know or read? Thanks!
Here a description of how the import directive works. Without knowing the actual error T4 reports when transofrming the template in your environment, I can only guess that you didn't add an assembly directive to reference the System.Data.Entity.Design assembly. If this doesn't work, look at the errors reported by T4 in the Error List of visual studio, which should be more helpful than "ErrorGeneratingOutput".