I can't seem to find where I might be able to suppress these specific errors
or why they are even registering in the first place.
error: empty paragraph passed to '#param' command
Here is the documentation that I have that is generating this error:
//----------------------------------------------------------
///
/// #brief functionThatModifiesSomething
///
/// #param[in] param1
/// #param[in] param2
///
//-----------------------------------------------------------
void functionThatModifiesSomething(uint32_t param1, uint32_t param2);
I only noticed this because I am finally turning on some of these warnings and I'm cleaning up as I go.
After seeing the warning, I don't understand why it is registering an error when the #param is not an empty paragraph. Any thoughts? Can I suppress this flavor of documentation warning somehow?
Here is the full error:
./path/to/somefile.hpp:570:21: error: empty paragraph passed to '#param' command [-Werror,-Wdocumentation]
/// #param param1
~~~~~~~~~~~~^
We are using Doxygen as our documentation format.
#param expects a description to follow the parameter name, which is missing in the above.
So a possible fix may be:
/// #param[in] param1 Description #1
/// #param[in] param2 Description #2
See http://www.doxygen.nl/manual/commands.html#cmdparam for #param documentation.
Clang's documentation warnings are enabled with -Wdocumentation, which is disabled by default. There's a whole bunch of documentation warning from different kinds, which are all enabled by -Wdocumentation, but unfortunately you can't opt out from individual warnings such as the "empty paragraph passed to #command" warning.
Related
I'm trying to create a custom outliner for VSCode (currently only for python), but I don't find measures to get the information I needed.
I like to get information in this manner this:
Array:
[0]
label: "foo"
type: "Function"
parameters: [...]
Range: [...]
innerDefinitions: [0]
[1]
label: "myclass"
type: "Class"
base_class: ""
Range: [...]
innerDefinitions:
[0]:
[...]
[1]:
[...]
Currently I try to get outline information via vscode.commands.executeCommand( 'vscode.XXX'
What I've tried:
Here is what commands I've tried and what result I received.
vscode.executeImplementationProvider
half usable: range of functionname. Other information is missing
vscode.executeHoverProvider
half usable: string of function head (including def keyword)
vscode.executeDefinitionProvider
half usable: range of complete function. Individual information must be "parsed out"
vscode.executeTypeDefinitionProvider
Never provided any result
vscode.executeDeclarationProvider
Never provided any result
vscode.executeDocumentSymbolProvider
Goes in a good direction. However
(1) Does only work on the whole document (not single function)
(2) Does only return first-level entities (i.e. class methods are not included in result)
Is there any API call I've overseen?
I wonder how the built-in outliner works, as it contains all-level information.
You need to use vscode.commands.executeCommand<vscode.Location[]>("vscode.executeDocumentSymbolProvider", uri, position)
This will give you the full outline of one file. There is no way to receive a partial outline.
Note: innerDefinitions are called children here.
Regarding the detail of the outline:
How detailed (and correct) an outline is going to be, depends on the implementation of the provider. Also, provider's information is no necessarily consistent among languages. This is very important to keep in mind!
At the moment (2021/03), the standard SymbolProvider for...
... Python will have a child for each parameter and local variable of a function. They will not be distinguishable
... C++ will contain no children for parameters. But it will have the parameter types in its name. (e.g. name of void foo(string p) will be foo(string): void.
As you can see, both act differently with their own quirks.
You could create and register a DocumentSymbolProvider yourself, that would return a level of detail you need (see VSCode Providers)
Also see: https://stackoverflow.com/a/66486297/6702598
In all my APIs I have a line of text that gets repeated. Is there a way to put that text in one place and link to it from the APIs?
For instance, in the below example, how to put the 'text that is common for many APIs' in one place, instead of writing the same thing in all the APIs?
/**
* #brief Function description
* #param [in] param function param description
* #return return description
*
* #attention text that is common for many APIs
***********************************************************************/
int func(int param);
In case it is always the same line, best would be to define a special command for it by means of and alias in the doxygen configuration file (Doxyfile), see the tag ALIASES
For longer texts the doxygen command \includedoc would be the way to go.
I need to set a message verbosity using a variable, e.g.:
my_write(my_verb : message_verbosity) is {
message(BUS, my_verb, vt.text_style(PURPLE, "txt txt txt"));
// other logic
};
This code causes the next compilation error:
*** Error: The verbosity parameter must be a constant of type 'message_verbosity'.
But actually even when I've defined the verbosity as constant field:
const my_verb : message_verbosity;
my_write() is {
message(BUS, my_verb, vt.text_style(PURPLE, "txt txt txt"));
};
I've got the same compilation error.
How the message verbosity can be passed in a variable to the message() action?
Thank you for your help
You are misunderstanding the message verbosity concept.
Every message has a fixed verbosity. Then you control from the prompt, what the unit's verbosity is, which has the message.
The content of the message doesn't change. You want to control, if the unit (with the message) is talking more or less.
You control the unit's verbosity using the "set verbosity ... sys.path.to.unit.inst" command.
In one of my scripts I use the Getopt::Long library. At the beginning of the program I make a call:
&GetOptions ('help', 'debug', 'user=s' => \$GetUser);
The first two arguments are simple: I discover their existance by checking $opt_help and $opt_debug respectively. However the third argument is tricky, because I need to distinguish between no option at all ($GetUser is undefined, which is ok for me), using "--user" alone ($GetUser is also undefined, but this time I want to display an error message) and "--user FooBar" (where the $GetUser receives 'FooBar', which I can use in further processing).
How can I distinguish between using no "--user" option and using it alone, without a username?
You are looking for : instead of =, so 'user:s' => \$GetUser. From Options with values
Using a colon : instead of the equals sign indicates that the option value is optional. In this case, if no suitable value is supplied, string valued options get an empty string '' assigned, while numeric options are set to 0
This allows you to legitimately call the program with --user and no value (with = it's an error). Then you only declare my $GetUser; and after the options are processed you can tell what happened. If it is undef it wasn't mentioned, if it is '' (empty string) it was invoked without a value and you can emit your message. This assumes that it being '' isn't of any other use in your program.
Otherwise, when you use 'user=s' and no value is given, the GetOptions reports an error by returning false and emits a descriptive message to STDERR. So you may well leave it and do
GetOptions( 'user=s' => ...) or die "Option error\n";
and rely on the module to catch and report wrong use. Our own message above isn't really needed as module's messages clearly describe the problem.
One other way of doing this would go along the lines of
usage(), exit if not GetOptions('user=s' => \$GetUser, ...);
sub usage {
# Your usage message, briefly listing options etc.
}
I'd like to add – you don't need & in front of a function call. It makes the caller's #_ visible, ignores function prototype, and does a few other similarly involved things. One common use is to get a coderef, $rc = \&fun, where it is needed. See for example this post
I'm sorry if it sounds too simple a question but still ...
I am documenting php code and whereas all functions etc. look good in the generated documentation,
I have problems with variable types which should be visible in the generated documentation.
I document them in this way:
/**
* $request - request object
*
* #type int
* #access private
*/
private $request;
As a result, I can see 'int' in the generated documentation, but #type is not a correct command. The proper command would be #var instead of #type but then I cannot see the type of the variable in the documentation.
So the question is "How to document a variable so I can see its type?"
Please help :)