I use doxygen to document C++ code. In the current project, I use the following format for function signatures:
MyClass(MyClass&& other)
However, in the generated HTML documentation, the brief description has this signature:
MyClass (MyClass &&other)
and the detailed description has this signature:
MyClass ( MyClass && other )
Is there a way of either preserving the original format, or changing the way doxygen formats the signatures? I have not found anything related to this issue in the customization or configuration pages.
Edit: Updated the signatures based on the discussion in the comments.
Short answer: No.
Long (and more correct) answer: Yes, if you're willing to modify the source code.
File memberdef.cpp has the following (line 1668 in what I'm looking at today):
// *** write arguments
if (argsString() && !isObjCMethod())
{
if (!isDefine() && !isTypedef()) ol.writeString(" ");
That last line is going to add space in the brief description. (I've verified this by removing it and recompiling.)
As for the detailed description, that sets up a table, with <td>(</td> opening the arguments list. You might get rid of that space more easily, but doing it well will probably require monkeying with the source code.
I guess the best option is to roll your own, or to request a feature addition from the developers.
Related
In PhpStorm (and other JetBrains IDE), is it possible to make function attributes as file / resource path?
E.g. in this function:
function mix($file): string
{
// check mix maninfest for $file and return path from mix manifest
return $fire_path_with_cachebuster;
}
I'd like PHP to suggest files in the project as I define $file attribute when calling mix function.
Only manually for the moment, when calling that function 😒. And it's a temp injection (for a session) so it's not convenient:
mix('')
Place caret inside the string parameter
Use Alt + Enter (or via light bulb icon) to bring the Quick Fix / Intentions menu (on some Keymaps it might be different one)
Use "Inject language or reference" option
Then choose "File Reference" entry there (just start typing to filter the list).
The result:
Hopefully they will implement the following tickets for a permanent solution:
Using #[Language] PHP attribute at the function declaration: https://youtrack.jetbrains.com/issue/WI-56996
Or in-place via PHPDoc-like comment (before the parameter when calling that function): https://youtrack.jetbrains.com/issue/WI-20028
Watch those tickets (star/vote/comment) to get notified on any progress (and hopefully speed it up by bringing dev's attention).
Like LazyOne stated, there is currently no way to declare a parameter as being a file reference.
However, you can get a more permanent File Reference "injection" by [mis]using __DIR__.
PhpStorm considers a string mixed with the __DIR__ constant to be a file path:
It isn't perfect as it depends on what directory you are currently located in. If you only want the filename passed to your method, you can wrap the string in basename, or handle that from within your method.
echo mix(basename(__DIR__ . '/slack_bot.php'));
I am trying to find a clean way to access the regmap that is used with *RegisterNode for creating documentation and testing files. The TLRegisterNode has methods for generating the json through some Annotations. These are done in the regmap method by adding them to the ElaborationArtefacts object. Other protocols don't seem to have these annotations.
Is there anyway to iterate over the "regmap" Register Fields post elaboration or during?
I cannot just access the regmap as it's not really a val/var since it's a method. I can't quite figure out where this information is being stored. I don't really believe it's actually "storing" any information as much as it is simply creating the hardware to attach the specified logic to the RegisterNode based logic.
The JSON output is actually fine for me as I could just write a post processing script to convert JSON to my required formats, but I'm wondering if I can access this information OR if I could add a custom function call at the end. I cannot extend the case class *RegisterNode, but I'm not sure if it's possible to add custom functions to run at the end of the regmap method.
Here is something I threw together quickly:
//in *RegisterRouter.scala
def customregmap(customFunc: (RegField.Map*) => Unit, mapping: RegField.Map*) = {
regmap(mapping:_*)
customFunc(mapping:_*)
}
def regmap(mapping: RegField.Map*) = {
//normal stuff
}
A user could then create a custom function to run and pass it to the regmap or to the RegisterRouter
def myFunc(mapping: RegField.Map*): Unit = {
println("I'm doing my custom function for regmap!")
}
// ...
node.customregmap(myFunc,
0x0 -> coreControlRegFields,
0x4 -> fdControlRegFields,
0x8 -> fdControl2RegFields,
)
This is just a quick example I have. I believe what would be better, if something like this was possible, would be to have a Seq of functions that could be added to the RegisterNode that are ran at the end of the regmap method, similar to how TLRegisterNode currently works. So a user could add an arbitrary number and you still use the regmap call.
Background (not directly part of question):
I have a unified register script that I have built over the years in which I describe the registers for a particular IP. It works very similar to the RegField/node.regmap, except it obviously doesn't know about diplomacy and the like. It will generate the Verilog, but also a variety of files for DV (basic `defines for simple verilog simulations and more complex uvm_reg_block defines also with the ability to describe multiple of the IPs for a subsystem all the way up to an SoC level). It will also print out C Header files for SW and Sphinx reStructuredText for documentation.
Diplomacy actually solves one of the main issues I've been dealing with so I'm obviously trying to push most of my newer designs to Chisel/Diplo.
I ended up solving this by creating my own RegisterNode which is the same as the rocketchip RegisterNodes except that I use a different Elaboration Artifact to grab the info and store it for later.
What does the two colons before the toString() method invocation mean?
For instance, I found the following code:
orderXml.ns::['status'].toString();
Is it the same as ['status'].toString().call(orderXml.ns);?
I am using the Demandware Script above.
Thank you.
In Demandware Script you'll find that a long-deprecated concept called E4X which extends the JavaScript 1.6/ES3 syntax still exists. However, it's usage is now discouraged. You can find some documentation for this syntax here: https://developer.mozilla.org/en-US/docs/Archive/Web/E4X/Processing_XML_with_E4X
In the script snippet you provided, the colons are used to identify the XML namespace of the following expression. Without that namespace, you may find that the incorrect object is referenced or you may get an undefined reference. See the specific area of the documentation archive linked above that pertains to Namespaces: https://developer.mozilla.org/en-US/docs/Archive/Web/E4X/Processing_XML_with_E4X#Handling_namespaces
The code essentially looks for an object property with the name: status. This isn't actually Array notation as it appears upon cursory inspection. Specifically, it looks for a namespaced property. It would not be the same as calling:
['status'].toString().call(orderXml.ns);
The .toString() method is used to ensure we get the String representation of the property rather than a reference to an instance of that XML Node.
Please note that Demandware uses a modified version of the Mozilla Rhino 1.7R5 JavaScript implementation. See feature matrix here: https://mozilla.github.io/rhino/compat/engines.html
I've seen that some projects used _ function that takes string as an argument, like _("Hello World"). But I couldn't find any manuals or articles about what is it and how to use it.
I guess this has something to do with i18n and l10n (it was mentioned in some article I found on the internet), but can you explain to me how it works and how to use it?
That is the GNU gettext localization function. You can provide language specific alternate strings for the one specified in the function call.
There is the xgettext tool, which generates a .pot file (abbreviation for portable object template) from your application code, then translators can make .po localization files for it. Then, you can bundle these with your application, and deliver a more widely usable piece of software.
I18n. See gettext example here: https://ewgeny.wordpress.com/2012/05/10/supporting-multiple-languages-in-your-application-a-simple-gettext-step-by-step-example/
Also found some info about what exactly this function do, it seems to be the macro for Glib.dgettext() function in Vala, this is from valadoc.org:
dgettext
public unowned string dgettext (string? domain, string msgid)
This function is a wrapper of dgettext which does not translate the message if the default domain as set with textdomain has no translations for the current locale.
...
Applications should normally not use this function directly, but use the _ macro for translations.
I use Doxygen for documenting the JavaScript API of my C++ (Qt) project. The idea is to write one specific documentation for the JavaScript interfaces, and one for the C++ classes us usual.
One example (datasource.dox) looks like this:
\addtogroup JavaScriptAPI
#{
...
\class DataSource
\brief DataSource is the .... some doc goes here ....
\section formats Supported formats
....
\fn isOpen()
\brief returns true if the data source is currently open...
...
#}
The generated help looks nice w.r.t. the class description (or 'object'-description), but the function documentation (isOpen(), ...) is missing. Doxygen creates warning messages like:
Warning: documented function `bool isOpen' was not declared or defined.
The question, now: can I somehow force doxygen to use my \fn-d function descriptions? It would be nice, if doxygen created all those member indices for me...
Two approaches for using doxygen with Javascript are listed here http://www.doxygen.org/helpers.html
(look for JavaScript)