Unlike in flex, /* */ and \\
don't seem to work in jlex. They give the error,
"Missing brace at start of lexical action."
You can include comments in the first and third sections of your JLex specification (which are the definition and java code sections), but not in the second (rules) part, because JLex will think they are part of a pattern.
Write %state DUMMY
in the declaration section and then writing comments in the rules section like this:
<DUMMY>. { /* this is my comment */ }
Related
I have few functions, that should be described in doxygen where 80% of description is the same.
I can copy-paste it over them, but sometimes this description is changing, and supporting changes in all those functions is becoming headache.
Is there a way in doxygen to create a named text block, that will be typed just once, and each function will be able to use it?
Something like that:
//! /textblock <supername> that is the text that I would like to have just once, but that should appears in different places in documentation
...
//! my function 1. /useblock <supername>. Just as it is.
void func1() { return; }
...
//! my function 2. /useblock <supername>. Yeah, make sense.
void func2() { return; }
...
//! my function 3. /useblock <supername>. Such great it is.
void func3() { return; }
I've used the "alias" custom command in doxygen for implementing "snippets". See http://www.doxygen.nl/manual/custcmd.html. Although the explanation makes it look like you can use this only for function-type things, it's great for repeated text.
Using Doxygen version 1.8.4:
When AUTOLINK_SUPPORT = NO in the configuration file, the HTML See Also section references generated by \sa (or #see) are not active links to the referenced method. When AUTOLINK_SUPPORT = YES the \sa references are active links as expected.
This seems to be a relatively recent change to doxygen behaviour: I've been using AUTOLINK_SUPPORT = NO for years to avoid having to mark all the words in the description text that would otherwise result in undesired automatic links with a '%' character, and the See Also references had remained active links.
Is there a known workaround that enables \sa references to remain active links while still having global AUTOLINK_SUPPORT disabled?
Here is a trivial test file:
/** The Fooy class.
*/
class Fooy
{
public:
/** foo
The alternative is {#link bar(int, int)const the bar method}
#param value A value.
#return The value incremented.
#see bar(int, int)const
*/
int foo (const int value) const;
/** bar
The alternative is {#link foo(const int)const the foo method}
#param value A value.
#param number A number.
#return The value plus the number.
#see foo(const int)const
*/
int bar (int value, int number) const;
};
Using the auto-generated Doxyfile (doxygen -g) doxygen version 1.8.8 produces, without any warnings, the expected HTML results: The {#link bar(int, int)const the bar method} syntax results in a link named "the bar method" (and likewise for the other #link), and the #see references result in the expected links having the method signatures.
If the Doxyfile is changed so AUTOLINK_SUPPORT = NO doxygen now produces HTML in which the #see signatures are no longer links, but is otherwise the same.
If " the bar method" is removed from the first #link command doxygen outputs -
Fooy.hh:9: warning: unable to resolve link to `bar(int, int)' for \link command
And the resulting HTML has the single word "const" as the link to the html/classFooy.html file instead of the method signature and correct link. However, if the single space is removed after the comma in the argument list of the method signature the warning disappears and the link is now correct with the full signature text. Note that the space character
in the foo argument list of the second #link command must remain to have a correct signature, so removing the text " the foo method" from the command will always result in an incorrect parsing by doxygen. Restoring AUTOLINK_SUPPORT = YES does not change this behaviour. This suggests a flaw in the doxygen parser.
Back to the initial issue of getting the #see references to be links in the HTML output when AUTOLINK_SUPPORT = NO in the Doxyfile. Putting the method signatures in the #see commands inside {#link ...} wrappers fails as described above (only if the method signature has no space character does it work correctly). If the wrappers are replaced with the new #link ... #endlink syntax (and the new syntax used with the other {#link ...} commands) then the HTML output from doxygen is the expected results with full method signatures and correct links.
So the answer to this problem is that doxygen is not backwards compatible with previous in-code command syntax. Unless some workaround is known, all existing code files must be edited to accommodate the changes to the doxygen parser.
Sigh.
I want to use Play Templates to generate source code for a programming language.
I'd like to add support for a custom format to the template engine as per Play's documentation. But I do not understand:
1) Where to specify a new file extension? templatesTypes += ("code" -> "some.lang.LangFormat")
in build.sbt?
2) how to stop Play from escaping HTML characters and adding blank lines
Has anyone got experience with Play custom template formats?
If possible please provide links to examples.
1) The extension in your example would "code", so for example, for a python template generator, you would do:
templateTypes += ("py" -> "some.python.PythonFormat")
2) The thing that escapes HTML characters is the some.lang.LangFormat class, which has to implement the play.api.template.Format class. This has the following two methods:
/**
* A template format defines how to properly integrate content for a type `T` (e.g. to prevent cross-site scripting attacks)
* #tparam T The underlying type that this format applies to.
*/
trait Format[T <: Appendable[T]] {
type Appendable = T
/**
* Integrate `text` without performing any escaping process.
* #param text Text to integrate
*/
def raw(text: String): T
/**
* Integrate `text` after escaping special characters. e.g. for HTML, “<” becomes “<”
* #param text Text to integrate
*/
def escape(text: String): T
}
So you can just make escape delegate to raw if you don't want to do any escaping.
As far as controlling line breaks goes, this is an aspect of the templates themselves, if you put line breaks in a template, they will appear in the result. So for example:
#if(foo) {
#bar
}
Will have line breaks, whereas:
#if(foo) {#bar}
won't.
I'm a Perl programmer for a long time, but I always have problems with documentation in POD.
When I use POD comments in the code, the code is difficult to read. When I use POD comments at the end of file, there is the danger that the documentation is not in sync with the code.
I miss a documentation style similar to Java.
/**
* #description
* ...
*/
I look for an easier and more intuitive documentation style. Is there such a thing?
A quick search found Doxygen Filter which purports to allow you to use Doxygen style comments (which are very close to Javadoc) to document Perl code.
Well, POD's the accepted standard for publishing Perl documentation.
I do find it rather annoying to maintain as well; I've recently experimented with using Pod::Weaver to maintain the documentation and build it into Pod on release. It's a little bit tricky in that it's quite flexible in how you filter and build the POD, and could do with a little more documentation (in POD or otherwise). But seems promising. Still too early for me to give more of a judgement than that, but it seems promising.
Hope this helps
Why do you think the code is hard to read with Pod? Is the code hard to read with other code around it? Perhaps you're putting too much into a particular part of the code, instead of writing small methods, etc. Are you sure it's not your code that's hard to read?
You don't have to put all of your documentation at the end of the code. Pod is perfectly fine inline with code, allowing you to put the documentation for a subroutine or method right next to the subroutine or method.
Is there some other problem you have with Pod?
The only time I have had a problem with POD is when using a text editor that doesn't highlight it correctly.
Just like everything in Java this seems overly verbose:
/**
* Returns an Image object that can then be painted on the screen.
* The url argument must specify an absolute
{#link URL}. The name
* argument is a specifier that is relative to the url argument.
* <p>
* This method always returns immediately, whether or not the
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives
* that draw the image will incrementally paint on the screen.
*
*
#param url an absolute URL giving the base location of the image
*
#param name the location of the image, relative to the url argument
*
#return the image at the specified URL
*
#see Image
*/
public Image getImage(URL url, String name) {
try {
return getImage(new URL(url, name));
} catch (MalformedURLException e) {
return null;
}
}
When compared to the equivalent Perl.
=item getImage( url, name )
This method always returns immediately, whether or not the
image exists. When this applet attempts to draw the image on
the screen, the data will be loaded. The graphics primitives
that draw the image will incrementally paint on the screen.
url must be an absolute URL giving the base location of the image
name is the location of the image, relative to the url argument
=cut
sub getImage{
my ($url,$name) = #_;
...
}
You might want to take a look at Rinci. Examples of applications which use this: File::RsyBak, Git::Bunch, App::OrgUtils.
Here's how you document modules. You declare %SPEC in your module and put documentation inside it. Each function gets its own key. There are predefined fields. Localization is supported. The formatting is done in Markdown. An example:
$SPEC{':package'} = {
summary => 'Module to do foo',
"summary.alt.lang.id_ID" => "Modul untuk melakukan foo",
description => <<EOT,
Blah...
...
EOT
links => [...],
};
$SPEC{func1} = {
summary => '...',
description => '...',
args => {
arg1 => {
schema => ...,
summary => ....,
description => ...,
},
},
examples => [...],
links => [...],
...
};
Instead of using Java- or Perl 5 style of putting documentation in "comments", it uses data structure directly available to the programs. (Note that Perl 6 is also going this way.) Think of it as Python docstring gone crazy (or structured).
There are tools to generate POD, text, HTML from the metadata (spec). Aside from documentation, the metadata is also useful for other things like argument validation, command-line interface, etc.
Disclosure: I'm the developer.
Myself, I often find wanting to reproduce code entries to documentation.
Yet to find how I can trick POD to read the code when podding whilst letting the code execute whilst parsing.
Do I really have to settle for this:
=head1 Variables
use vars (%V &C)
=cut
use vars (%V %C)
=head2 Constants
$C{hashConstant1} = "/path/to/file"
=cut
$C{hashConstant1} = "/path/to/file";
=head2 Variables
$V{strVar1} = undef
=cut
$V{strVar1} = undef;
Then again, most languages require the double typing to document.
I am trying to figure out if there is a way to create a custom tag using Doxygen. I did find the ALIAS configuration file option but that does not do exactly what I need. Basically in my code I want to be able to write something like
/// \req Requirement #322 - blah blah
And then have Doxygen create a list like it does for \bug and \todo commands for lines that have this custom tag. Is this possible with Doxygen?
The generalization of \bug and \todo is \xrefitem.
The solution I suggest is:
in Doxyfile:
ALIASES += "req=\xrefitem req \"Requirement\" \"Requirements\" "
in documented code:
/// \req #42 - The system shall work in any situation
Thanks mouviciel! I have adopted your solution and extended it for my purposes.
The text below goes into my Doxyfile:
ALIASES += req{1}="\ref SRTX_\1 \"SRTX-\1\" "
ALIASES += satisfy{1}="\xrefitem satisfy \"Satisfies requirement\" \"Requirement Implementation\" \1"
ALIASES += verify{1}="\xrefitem verify \"Verifies requirement\" \"Requirement Verification\" \1"
Where SRTX is the name of my project and is used as a prefix to requirements.
Then I create a file called Requirements.dox that provides a link between the requirement id and a URL for the requirement in my requirements management tool (an issue tracker in my case).
/**
#page Requirements
#section Build1
#anchor SRTX_1113
SRTX-1113
#anchor SRTX_1114
SRTX-1114
*/
One could also put the text of the requirement in the anchor tag if you didn't need to link to an external source.
In my code I have:
/**
* This is the basic executive that schedules processes.
* #satisfy{#req{1114}}
*/
class Scheduler: public Process
{
...
}
And in my tests I put:
/**
* Provide a number of tests for process scheduling.
* #verify{#req{1114}}
*/
class Scheduler_ut : public CppUnit::TestFixture
{
...
}
This gives me related pages for Requirements, Requirements Implementation, and Requirements Verification. It also provides Satisfies requirement and Verifies requirements sections in the class description (or function -- wherever you put the tag).
Combining the two answers above, you can have a single clean requirement tag that will build a cross-reference table, and, also provide a direct link to the requirement repo in your docs:
Doxygen CONFIG file:
ALIASES = "requirement{1}=#xrefitem requirement \"Requirements\" \"Requirements Traceability\" \1"
Source code:
#requirement{REQ-123} Brief textual summary of this requirement item
This will render in the documentation as:
Requirements:
REQ-123 Brief textual summary of this requirement item