Doxygen shows a Compound ? is not documented. warning when building. For a specific project I don't want to document Compounds. To remove clutter I want to see all other warnings except that one. Is there a way to clean the Doxygen output?
I don't think this is possible, except by writing your own post-processor to filter doxygen output. In your case, this should not be too hard, a simple grep should be sufficient:
doxygen <config_file> | grep -v "warning: Compound .* is not documented"
I'm not really sure why doxygen does not provide this feature: perhaps it would require too much options, or more complicated options. Another possibility is that they assumed that since you want to be warned when something is not documented, there should be no exceptions except when explicitly specified in the source code (using \cond and \endcond, for example), with the rationale that this kind of omission should only be decided on a case-by-case basis. Or perhaps nobody ever asked them to include this feature: feel free to fill in a feature request.
I think what you're looking for is the if, ifnot and endif commands. Just decide an appropriate label then use the correct tag. Ex.:
/*
* \if DISPLAY_COMPOUND
* Compound doc.
* ...
* \endif
*/
doxygen will evaluate if it knows of this label and if it doesn't, he'll ignore any comment up to the \endif command in the same comment block
Then you need to define (or not) that label in your doxyfile in the ENABLED_SECTIONS.
#comment the next line if you don't want to document Compound
ENABLED_SECTIONS = DISPLAY_COMPOUND
Have a look at the \cond and \endcond commands too which are similar but not quite the same (they enable or disable entire sections of a file, not just a single comment block).
You can switch off warnings in the doxygen configuration.
See here: doxygen documenation
My favorite is: WARN_IF_UNDOCUMENTED = NO
Related
I have a few related questions about pragmas. What got me started on this line of questions was trying to determine whether it's possible to disable some warnings without going all the way to no worries (I'd still like to worry, at least a little bit!). And I'm still interested in the answer to that specific question.
But thinking about that issue made me realize that I don't really understand how pragmas work. It's clear that at least some pragmas take arguments (e.g., use isms<Perl5>). But they don't seem to be functions. Where do they fit into the overall MOP? Are they sort of like Traits? Or packages? Is there any way to introspect over them? See what pragmas are currently in effect?
Are pragmas built into the language, or are they something that users can add? When writing a library, I'd love to have some errors/warnings that users can optionally disable with a pragma – is that possible, or are they restricted to use in the compiler? If I can create my pragmas, is there a practical difference between setting something with a pragma versus with a dynamic variable, aside from the cleaner look of a pragma? For that matter, how do we decide what language features should be set with a pragma versus a variable (e.g., why is $*TOLERANCE not a pragma)?
Basically, I'd be interested in any info about pragmas that you could offer or point me towards – though my specific question is still whether I can selectively turn off certain warnings.
Currently, pragmas are hard-coded in the handling of the use statement. They usually either set some flag in a hash that is associated with the lexical scope of the moment, or change the setting of a dynamic variable in the grammar.
Since use is a compile time construct, you can only use compile time constructs to get at them (currently) (so you'd need BEGIN if it is not part of a use).
I have been in favour of decoupling use from pragma's in the past, as I see them as mostly a holdover from the Perl roots of Raku.
All of this will be changed in the RakuAST branch. I'm not sure what Jonathan Worthington has in mind regarding pragmas in the RakuAST context. For one thing, I think we should be able to "export" a pragma to the scope of a use statement.
Each time I need anything beyond the standard search, I find myself trying several things, searching Google and in the end terribly failing. Apparently, the Hg search syntax is pretty extensive and I would like to use its power, but I don't seem to be able to find a good reference.
For instance, quite often I want to find all changes in the repository related to a partial path match. I know that the following works:
file('path:full/path/file.txt')
But I would like to search for files by partial match, and neither of the following worked:
jquery -- seems to find everything
file(jquery*) -- finds nothing
file('jquery*') -- finds nothing
file('path:jquery.*') -- finds nothing
file('name:jquery.*') -- finds nothing
file('path:jquery.js') -- finds every revision, it seems
From the popup in TortoiseHg I see that there are a gazillion options, but no hint on how to use them (the help link shows a little bit more, but nothing on what a pattern should look like in file(pattern)):
In the end I usually find what I want using other ways of searching, but it would be so nice to be able to use this power of expression, and it's quite a shame that after so many years, I've never found out how to leverage this.
I can very much advise using the hg help system for this. The most useful pages to look at (in my view):
hg help revsets
hg help filesets
hg help patterns
In the page about patterns, you can find about 'path:':
To use a plain path name without any pattern matching, start it with
"path:". These path names must completely match starting at the current
repository root.
In other words: using 'path:' is not suitable for this purpose. Slightly below, 'glob:' is mentioned:
To use an extended glob, start a name with "glob:". Globs are rooted at
the current directory; a glob such as "*.c" will only match files in the
current directory ending with ".c".
The supported glob syntax extensions are "**" to match any string across
path separators and "{a,b}" to mean "a or b".
In other words, it should be possible to use the pattern file('glob:**jquery*').
In fact, the above pattern would also work without the glob prefix, so: file('**jquery*'). See part of the page about revsets:
"file(pattern)"
Changesets affecting files matched by pattern.
For a faster but less accurate result, consider using "filelog()"
instead.
This predicate uses "glob:" as the default kind of pattern.
Say I have a view helper that outputs something like this as a string:
'<div class="tag"><a href="posts/tagname"Tagname</a></div>'
How can I do something like this in Rspec?
the_string.should be_valid_html
I have looked at be_valid_asset, but it requires a network connection to hit the W3C servers and this really isn't necessary (plus it mangles the CI server). All I need is to make sure it isn't missing an angle bracket or something. Regexp seems like the wrong solution for parsing HTML (yes, I've seen that answer).
Although I haven't used it, here's a gem that claims to do what you're looking for:
https://github.com/ericbeland/html_validation
Not a direct answer but I don't think it's necessary to write tests for such details in view. Too much tests to write otherwise.
If all you need to is to ensure no missing bracket, I would suggest you to use Haml or Slim for templating. Any errors will be thrown and you don't even have a chance to write brackets in most cases.
I would like to program a parser for a Markup language similar to BBCode, Markdown, Wikisyntax etc. using a high-level language like Python or Perl. It should feature sectioning, code highlighting, automatic link creation, embedding images but allowing HTML for more complex formatting.
Has anyone done similar things or has worked closely with those systems and could describe generally how this could be done efficiently?
Although efficiency is not really of concern for such a small system, it is generally favourable.
In particular I would like to learn if there is a more efficient way than using regular expressions for such a program.
For your general discussion…
You should start with the following blueprint:
you need to iterate charwise over entire data
you need to identify every char by its context, for it may be a tag-opening ('<', '[' etc) or just the char. This may be done by having an escapement flag, triggered by an escape-char (like backslashes in some languages do). if you use that approach, you also need to check for an escaped escapement.
you may also need some flag telling you to be inside a comment or special data section, that may have different escapement rules.
you need to build a tree-like structure or at least some stack for nested tags. This is why regexes are a bad idea: they not only take much to much overhead, they're also of no use if you want to get the correct closing tag for the second x (x=any tag) in the following snipped: <x><x><x></x><x><x></x></x><x></x><!-- </x> -->this one →</x><x></x></x>
What language(s) have comments with side effects? In essence, comments which are not comments....
English. Do I win?
DOS Batch Shell programming
The REM (Remark) allows you to put in a comment. But it has the side-effect of modifying the ERRORLEVEL variable to 0.
In a sense, it makes last operation a success.
I don't know how a comment can fail, but if it does, you are covered.
I can think of several places where comments aren't really comments.
HTML and script tags (providing support for browsers that don't allow or support scripts).
And then, considerably more obscurely:
IBM Informix 4GL (I4GL) and 4J's Genero (successor to Informix Dynamic 4GL, D4GL). The notation '--#' was used by D4GL to include material only applicable to D4GL; I4GL would see that as a comment. The inverse notation was '--#', which looked like a comment to D4GL but was treated as active material by I4GL.
And, even more obscurely:
I wrote an I4GL file which was dual-languaged, exploiting I4GL's multiple comment facilities. Material starting '#' (hash) marked the start of a comment outside of strings - up to the next newline, as does '--' (double-dash). Also, '{...}' (braces) enclose multiline comments.
The top of the source file was actually a shell script, mostly enclosed in '{...}' which is, of course, perfectly legitimate in shell. The shell script was a data-driven code generator that copied itself to the top of the output, and then generated about 100 functions which were all depressingly similar but slightly different (in a language without templates or a pre-processor). The code had to validate what was in the database for a given ship against incoming data from an external source (Lloyds of London, in fact), to see what had changed since the last time the external data was received. Non-trivial comparison work, especially since it had to deal with database (SQL) nulls.
The file was not really a Quine program, but it had some points in common with it. In particular, you could feed the script broken I4GL code and the regenerated file would be perfect again, basically because it ignored the existing I4GL code.
Haskell can turn the usual comments in code paradigm upside down by having code in comments - also Mathematica and the like; literal programming is a nice feature for the more mathematically inclined languages.
I also find annotations in Java are like comments with behaviour.
Then of course there are "polyglots" -- programs which can be compiled/executed in multiple languages. Usually these rely on the fact that the same line is a comment in one language, but an actual line of code in another.
QBasic has a use of comments all its own: REM $STATIC or REM $DYNAMIC set how arrays are allocated.
Another example: When web browsers parse comments <!-- -- -->in<!-- -- -->correctly.
CSS for clever cross-browser hacks. Of course, I wouldn't really call CSS a language.
Just stumbled upon this old question and my first thought was javadoc comments.