I want to add a comment like this
/**
* #param scrollFraction In range [0..1].
*/
But Dokka/Kdoc interprets stuff inside square brackets as a reference. This leads to badly rendered comments when you check the function's documentation in the IDE or generate the docs. How can I escape square brackets/other symbols in Dokka/Kdoc?
You should be able to do it using ` symbol, like this:
/**
* #param scrollFraction In range `[0..1]`.
*/
However, using ` symbol will show everything in between as a code block.
To just use square brackets without a reference inside, use HTML symbols, like [ and ] from the #yuvgin's answer.
You can use HTML escaping:
/**
* #param scrollFraction In range [0..1].
*/
should output in Dokka as range [0..1]., since [ escapes as [ and ] escapes as ].
Note this will not work inside a section of inline code (between grave accents - like this). For such cases use square brackets ([ and ]) normally, as was suggested in Demigod's answer.
Related
JavaScript contains the following syntax:
`hello ${name}`
I'm wondering how a Ragel machine would split the syntax above. The way I see it, the type of the closing curly brace depends on the parsing state. For example, in the code below the curly brace is instead part of the string token, since the ${ token isn't there:
`hello name}`
Finally, it becomes more tricky when you consider that the right curly can also be found within the variable expression itself, ie:
`hello ${() => { return name }()}`
How would a similar context-dependent grammar be implemented with Ragel?
The syntax inside of `` is not normally something you would handle with your lexical analyzer. Better to send it to your parser as a sequence of literal text and/or tokens. So you'd send "`" as opening, "hello " as some literal text, then the tokens "(", ")" etc. To know when to stop and go back to literal text you either need some feedback from your parser to to your scanner, or inside the scanner you need to balance the parens.
Note I've never actually made a parser for javascript, just going on what you provided above.
I was wondering about notation in the documentation of PostgreSQL.
[ ], { }, [ ... ], [ , ... ], ( ) etc...
You can see these signs from SQL query example etc.
What do these signs mean?
[square brackets] indicate optional parameters. You can include any number of these, or none.
(parentheses) are simply part of the SQL code, and does not indicate any deeper meaning in the documentation.
{curly braces} and verical lines | indicate that there are a limited amount of options to choose, and you must choose one alternative or another.
[] - There are called "square brackets"
{} - These are called "curly brackets".
() - These are simply called "brackets".
I hope I answered your question?
[ is a square bracket, ( is a round bracket, { is a curly bracket .... so I believe
Use the word left or right in front of them. The ones above are left
Round bracket also known as parenthesis
I do have some problems to define an Alias definition in doxygen when I have to use multiple commands in the alias definition.
What I am trying to achieve is actually the output of sample DD_32 below.
I currently don't know why the output of #DD{22, Test Description} looks different. Also tried to provide escaped quotes to the ALIAS definition, but still. No luck.
My alias definition is as follows:
ALIASES += DD{2}="\page DD_\1 \"Design \1\" \brief \2 #par Implementation:"
For testing I use the following code:
/**
* #page DD_31 Design 31
* #brief Descrition
* #par Implementation:
*/
/**
* #DD{22, Test Description}
*/
I would suspect, that the output is identical, but it looks like in the screenshot provided below:
As you can see, the \brief description is actually part of the page name.
Any hints how I could fix this issue?
Thanks a lot.
For completeness;
As proposed in the comments by albert, his pull request implements physical newlines in an alias by placing ^^ in between separate commands.
So, for example:
ALIASES += DD{2}="#page DD_\1 "Design \1" \brief \2 ^^ #par Implementation:"
The heading at the start of the comment block shown in the C code below is formatted incorrectly in both HTML and PDF output as \verbatim text.
All other Doxygen comments I have in this file work perfectly (they are all VERY similar as the file provides functions that conform to a type).
I have tried removing all preceding Doxygen comments from the file (except the #name) to rule out incorrect block formatting closing, removing the heading spec (#'s) changing the heading text (eg "foo") in case of incorrect characters, removing the later \verbatim block, removing this entire comment block itself to see if the problem transferred to the next one, but nothing seems to change!!
How can I get the heading to format correctly?? Thanks.
code:
/** # *IDN? - Identification query #
* This query allows the instrument to identify itself. It responds with a `<`string`>` consisting of four fields
* separated by commas. The four fields are determined by constants defined in the application
* specific settings in config.h and appear in the following order:
* \verbatim MANUF,MODEL,SERIAL,FIRMW \endverbatim
* See the config.h file description for information on each of these fields.
*
* #param parameters None
* #param query `*IDN?`
*/
extern int16_t IDN (double * parameters, bool query);
How this looks in PDF:
How this looks in HTML:
EDIT: The comments for the OPC function:
/** # *OPC - Operation Complete Command. #
* This command causes the device to set the operation complete bit in the standard event status register when
* all pending device operations have completed.
*
* The query responds with an ASCII "1" when all pending device operations are complete.
*
* #param parameters None
* #param query `*OPC?`
*/
extern int16_t OPC (double * parameters, bool query);
Finally solved this, though Im still unsure as to the cause.
Basically I rewrote the documentation comment a bit at a time (I was trying to see if I could isolate any one item that caused it).
I started with a one word comment, when that appeared correctly I slowly added more bits, rebuilding after each addition. I now have the full comment, exactly as before, but now working as intended
Puzzling... maybe doxygen only rebuilt that part after it detected the comment being deleted and started again and that cleared whatever the issue was?? Meh, it's fixed anyway. Thanks for the suggestions.
I'm trying to use Freemarker in conjunction with jQuery Templates.
Both frameworks use dollar sign/curly brackets to identify expressions for substitution (or as they're called in freemarker, "interpolations") , e.g. ${person.name} .
So when I define a jQuery Template with expressions in that syntax, Freemarker tries to interpret them (and fails).
I've tried various combinations of escaping the ${ sequence to pass it through Freemarker to no avail - \${, \$\{, $\{, etc.
Inserting a freemarker comment in between the dollar and the curly (e.g. $<#-- -->{expression}) DOES work - but I'm looking for a more concise and elegant solution.
Is there a simpler way to get a Freemarker template to output the character sequence ${?
This should print ${person.name}:
${r"${person.name}"}
From the freemarker docs
A special kind of string literals is the raw string literals. In raw string literals, backslash and ${ have no special meaning, they are considered as plain characters. To indicate that a string literal is a raw string literal, you have to put an r directly before the opening quotation mark or apostrophe-quote
For longer sections without FreeMarker markup, use <#noparse>...</#noparse>.
Starting with FreeMarker 2.3.28, configure FreeMarker to use square bracket syntax ([=exp]) instead of brace syntax (${exp}) by setting the interpolation_syntax configuration option to square_bracket.
Note that unlike the tag syntax, the interpolation syntax cannot be specified inside the template. Changing the interpolation syntax requires calling the Java API:
Configuration cfg;
// ...
cfg.setInterpolationSyntax(SQUARE_BRACKET_INTERPOLATION_SYNTAX);
Then FreeMarker will consider ${exp} to be static text.
Do not confuse interpolation syntax with tag syntax, which also can have square_bracket value, but is independent of the interpolation syntax.
When using FreeMarker-based file PreProcessor (FMPP), either configure the setting via config.fmpp or on the command-line, such as:
fmpp --verbose --interpolation-syntax squareBracket ...
This will call the appropriate Java API prior to processing the file.
See also:
https://freemarker.apache.org/docs/dgui_misc_alternativesyntax.html
http://fmpp.sourceforge.net/settings.html#templateSyntax
Another option is to use #include with parse=false option. That is, put your jQuery Templates into the separate include page and use parse=false so that freemarker doesn't try and parse it.
This would be a good option when the templates are larger and contain double quotes.
I had to spent some time to figure out the following scenarios to escape ${expression} -
In Freemarker assignment:
<#assign var = r"${expression}">
In html attribute:
Some link
In Freemarker concatenation:
<#assign x = "something&"+r"${expression}"/>
If ${ is your only problem, then you could use the alternate syntax in the jQuery Templates plugin like this: {{= person.name}}
Maybe a little cleaner than escaping it.
Did you try $$?
I found from the Freemarker manual that ${r"${person.name}"} will print out ${person.name} without attempting to render it.
Perhaps you should also take a look at Freemarker escaping freemarker
I can confirm that the
${r"${item.id}"}
is the correct way as an example.
So I kinda full example will look like
<span> Remove </span>
and the output will be :
<span> Remove </span>
In the case when you want to use non-raw strings so that you can escape double quotes, apostrophes, etc, you can do the following:
Imagine that you want to use the string ${Hello}-"My friend's friend" inside of a string. You cannot do that with raw strings. What I have used that works is:
${"\x0024{Hello}-\"My friend's friend\""}
I have not escaped the apostrophe since I used double quotes.