I'm using Doxygen to document C++ code, and am writing a substantial amount of Doxygen doc for the code. In one place I'm making a list of groups in the code, and would like it to appear as follows:
Control Module: the module that controls everything
Slave Module: the module that is the slave of the Control Module
My documentation source looks like this:
- #ref CM: the module that controls everything
- #ref SM: the module that is the slave of the #CM
But, problem: Doxygen seems to be reading the reference name as CM:, not CM, and thus can't find the reference. So, somehow I need to tell Doxygen where the reference name ends. (For example, if I were using Bash, and wanted to echo a variable string with an "s" as a suffix, I'd use echo "${NOUN}s".)
As a workaround, I could add a space between the name and the subsequent colon, but that makes the resulting doc harder to read and I'd like to avoid it.
Under Special Commands, the Doxygen manual includes the following hopeful-sounding information:
Some commands have one or more arguments. Each argument has a certain
range:
If <sharp> braces are used the argument is a single word.
If (round) braces are used the argument extends until the end of the line on
which the command was found.
If {curly} braces are used the argument
extends until the next paragraph. Paragraphs are delimited by a blank
line or by a section indicator.
OK, that's all fine and good, but the documentation doesn't say, and I can't figure out, where those braces are supposed to go. Around the argument alone? Around the entire command and argument? Neither works, and I can't come up with an alternative that does work.
So, how do I indicate the end of a reference name to Doxygen? And if braces are the answer, where do they go?
This works for Doxygen version 1.8.11:
\ref name "":
Apparently, the empty string triggers a fall-back to use the name argument before it.
The Doxygen documentation you quote is describing the syntax of the Doxygen documentation, not of sources to be parsed by your use of Doxygen.
In other words, if <sharp> braces are used when describing a command, it takes a single word; and so on.
Looking at the documentation of #ref:
\ref <name> ["(text)"]
The name argument is in "sharp braces," and so it's just a single word. Unfortunately, Doxygen seems to interpret : as part of that word. Your best bet would be to introduce a space:
#ref CM : the ...
You could also try whether a zero-width character would break the word recognition:
#ref CM: the ...
Related
Lets say that I have a c++ class that contains two c strings like below.
class PathExample {
char* partA; // Eg: "/some/folder/"
char* partB; // Eg: "SomeFile.txt"
}
I can make an lldb summary string for it:
type summary add PathExample --summary-string "${var.partA}${var.partB}"
However this adds unnecessary and confusing quotes "/some/folder/""SomeFile.txt".
How can I format the type summary string to not use quotes, or at least append the strings before adding quotes? Eg: "/some/folder/SomeFile.txt"
"Remove leading or trailing quote in the summary value" before adding to the output is a not supported by the summary string formatting options. We're trying to keep those options fairly streamlined, and that's a bit too much of a special purpose feature.
The thing that allows us to keep the summary string version fairly restrained is that you can always write a Python summary, which allows you to format up the output in whatever way you like. There's an example that's somewhat like what you want in the section on Python scripting:
https://lldb.llvm.org/use/variable.html#python-scripting
You wouldn't use GetValueAsUnsigned as that example does. The C-string rendering of char * types is actually done by a built-in summary, so you would use "SBValue.GetSummary" to get the string value. That's actually the same thing that's substituted into the summary string so it also has the quotes on it. But in Python it's trivial to strip the leading and trailing quotes before concatenating the two strings.
Note, though it's convenient for playing around with, you don't have to define the Python summary callback inline as shown in the example. You can put a function with the correct signature in a .py file somewhere, use command script import <path to .py file> and then import it using the -F option to type summary add. Remember to use the full name of the function (module_name.func_name) when you specify it. I have a bunch of these in a ~/.lldb directory and command script import them in my ~/.lldbinit.
help type summary add has some more details on how to do this.
During reading LLVM source code, I find something different in comments, e.g.
/// If \p DebugLogging is true, we'll log our progress to llvm::dbgs().
What does \p means here?
LLVM uses Doxygen for generating documentation, the /// marker is one of the many ways of creating a special comment block that Doxygen will parse to form documentation.
Within a special comment block, \p is simply one of the mark-up commands, this particular one renders the following word in typewriter font (fixed rather than proportional). The \c option is an alias for the same thing.
3 slashes is one of the ways that doxygen comments are identified.
The \p tag has some meaning, see it's documentation: https://www.doxygen.nl/manual/commands.html#cmdp
Displays the parameter using a typewriter font. You can use this command to refer to member function parameters in the running text.
I agree . These seems to be Doxygen commands to format typewritten fonts but since its in comments its not showing the 'font format' but the character itself.
Comments are not touched or processed by Doxygen. They have their own formatting. The /c /p precedes some important keywords (methods, members, parameters etc) only and not arbitrary. The author in all good intentions wanted people to identify the keywords but in comments, all are equal.
I've been using Doxygen to document my project but I've ran into some problems.
My documentation is written in a language which apostrophes are often used. Although my language config parameter is properly set, when Doxygen generates the HTML output, it can't parse apostrophes so the code is shown instead of the correct character.
So, in the HTML documentation:
This should be the text: Vector d'Individus
But instead, it shows this: Vector d'Individus
That's strange, but searching the code in the HTML file, I found that what happens is that instead of using an ampersand to write the ' code, it uses the ampersand code. Well, seeing the code is easier to see:
<div class="ttdoc">Vector d'Individus ... </div>
One other thing is to note that this only happens with the text inside tooltips...
But not on other places (same code, same class)...
What can I do to solve this?
Thanks!
Apostrophes in code comments must be encoded with the correct glyph for doxygen to parse it correctly. This seems particularly true for the SOURCE_TOOLTIPS popups. The correct glyph is \u2019, standing for RIGHT SINGLE QUOTATION MARK. If the keyboard you are using is not providing this glyph, you may write a temporary symbol (e.g. ') and batch replace it afterwards with an unicode capable auxiliary tool, for example: perl -pC -e "s/'/\x{2019}/g" < infile > outfile. Hope it helps.
Regarding the answer from ramkinobit, this is not necessary, doxygen can use for e.g. the Right Single quote: ’ (see doxygen documentation chapter "HTML commands").
Regarding the apostrophe the OP asks for one can use (the doxygen extension) ' (see also doxygen documentation chapter "HTML commands")).
There was a double 'HTML escape' in doxygen resulting in the behavior as observed for the single quote i.e. displaying '.
I've just pushed a proposed patch to github (pull request 784, https://github.com/doxygen/doxygen/pull/784).
EDIT 07/07/2018 (alternative) patch has been integrated in main branch on github.
I'm writing a long HOWTO in reStructuredText format and wondering if there's a way to let user specify values for a couple variables (hostname, ip address) at the top so the rest of the document would be filled with those automatically?
Like me, you are probably looking for substitution. At the bottom of the section you'll find how to replace text.
Substitution Definitions
Doctree element: substitution_definition.
Substitution definitions are indicated by an explicit markup start
(".. ") followed by a vertical bar, the substitution text, another
vertical bar, whitespace, and the definition block. Substitution text
may not begin or end with whitespace. A substitution definition block
contains an embedded inline-compatible directive (without the leading
".. "), such as "image" or "replace".
Specifically about text replacement:
Replacement text
The substitution mechanism may be used for simple macro substitution. This may be appropriate when the replacement text is
repeated many times throughout one or more documents, especially if it
may need to change later. A short example is unavoidably contrived:
|RST|_ is a little annoying to type over and over, especially
when writing about |RST| itself, and spelling out the
bicapitalized word |RST| every time isn't really necessary for
|RST| source readability.
.. |RST| replace:: reStructuredText
.. _RST: http://docutils.sourceforge.net/rst.html
reStructuredText is a markup language to define static content. HTML content (I assumed the desired output format is HTML) is typically generated from reStructuredText on build time and then released/shipped to the user.
To allow users to specify variables, you would need a solution on top of reStructuredText, for example:
Ship the content with a JavaScript plugin that dynamically replaces specific strings in the HTML document with user input.
Generate the documentation on-the-fly after the user has specified the variables.
Note that these examples are not necessarily particularly viable solutions.
Background
I use JScript (Microsoft's ECMAScript implementation) for a lot of Windows system administration needs. This means I use a lot of ActiveX (Automated COM) objects. The methods of these objects often expect Number or Boolean arguments. For example:
var fso = new ActiveXObject("Scripting.FileSystemObject");
var a = fso.CreateTextFile("c:\\testfile.txt", true);
a.WriteLine("This is a test.");
a.Close();
(CreateTextFile Method on MSDN)
On the second line you see that the second argument is one that I'm talking about. A Boolean of "true" doesn't really describe how the method's behavior will change. This isn't a problem for me, but my automation-shy coworkers are easily spooked. Not knowing what an argument does spooks them. Unfortunately a long list of constants (not real constants, of course, since current JScript versions don't support them) will also spook them. So I've taken to documenting some of these basic function calls with inline block comments. The second line in the above example would be written as such:
var a = fso.CreateTextFile("c:\\testfile.txt", /*overwrite*/ true, /*unicode*/ false);
That ends up with a small syntax highlighting dilemma for me, though. I like my comments highlighted vibrantly; both block and line comments. These tiny inline block comments mean little to me, personally, however. I'd like to highlight those particular comments in a more muted fashion (light gray on white, for example). Which brings me to my dilemma.
Dilemma
I'd like to override the default syntax highlighting for block comments when both the beginning and end marks are on the same line. Ideally this is done solely in my vimrc file, and not in a superseding personal copy of the javascript.vim syntax. My initial attempt is pathetic:
hi inlineComment guifg=#bbbbbb
match inlineComment "\/\*.*\*\/"
Straight away you can see the first problem with this regular expression pattern is that it's a greedy search. It's going to match from the first "/*" to the last "*/" on the line, meaning everything between two inline block comments will get this highlight style as well. I can fix that, but I'm really not sure how to deal with my second concern.
Comments can't be defined inside of String literals in ECMAScript. So this syntax highlighting will override String highlighting as well. I've never had a problem with this in system administration scripts, but it does often bite me when I'm examining the source of many javascript libraries intended for browsers (less.js for example).
What regex pattern, syntax definition, or other solution would the amazing StackOverflow community recommend to restore my vimrc zen?
I'm not sure, but from your description it sounds like you don't need a new syntax definition. Vim syntax files usually let you override a particular syntax item with your own choice of highlighting. In this case, the item you want is called javaScriptComment, so a command like this will set its highlighting:-
hi javaScriptComment guifg=#bbbbbb
but you have to do this in your .vimrc file (or somewhere that's sourced from there), so it's evaluated before the syntax file. The syntax file uses the highlight default command, so the syntax file's choice of highlighting only affects syntax items with no highlighting set. See :help :hi-default for more details on that. BTW, it only works on Vim 5.8 and later.
The above command will change all inline /* */ comments, and leave // line comments with their default setting, because line comments are a different syntax item (javaScriptLineComment). You can find the names of all these groups by looking at the javascript.vim file. (The easiest way to do this is :e $VIMRUNTIME/syntax/javascript.vim .)
If you only want to change some inline comments, it's a little more complicated, but still easy to see what to do by looking at javascript.vim . If you do that, you can see that block comments are defined like this:-
syn region javaScriptComment start="/\*" end="\*/" contains=#Spell,javaScriptCommentTodo
See that you can use separate regexes for begin and end markers: you don't need to worry about matching the stuff in between with non-greedy quantifiers, or anything like that. To have a syntax item that works similarly but only on one line, try adding the oneline option (:h :syn-oneline for more details):-
syn region myOnelineComment start="/\*" end="\*/" oneline
I've removed the two contains groups because (1) if you're only using it for parameter names, you probably don't want spell-checking turned on inside these comments, and (2) contained sections that aren't oneline override the oneline in the container region, so you would still match all TODO comments with this region.
You can define this new kind of comment region in your .vimrc, and set the highlighting how you like: it looks like you already know how to do that, so I won't go into more details on that. I haven't tried out this particular example, so you may still need a bit of fiddling to make it work. Give it a try and let me know how it goes.
Why don't you simply add a comment line above the call?
I think that
// fso.CreateTextFile(filename:String, overwrite:Boolean, unicode:Boolean)
var a = fso.CreateTextFile("c:\\testfile.txt", true, false);
is a lot more readable and informative than
var a = fso.CreateTextFile("c:\\testfile.txt", /*overwrite*/ true, /*unicode*/ false);