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.
Related
What I would like is to write something like this:
/**
* Takes a foo and {#link grokelates} it.
*/
function doSomething(foo) {
}
And have "grokelates" be a link to more detail on what "grokelate" means, but because I'm going to have functions dealing with grokelation all over my code base, I'd like to write that definition once and link to it in multiple places.
Is this possible?
To be clear, grokelates is not a function. It's just a word I want to define, but not have to define in-line everywhere I use it. I basically want to write a glossary file and be able to link to definitions from that glossary in my JSDoc.
Ideally this would also be in a way the VS Code picks it up and lets someone navigate to that definition on hover.
Yes there is. When you run jsdoc to generate your documentation, you can pass it any filetype you wish. A standard practice is to create one or more *.jsdoc files which contain doclet comments (those that begin with /**) to describe features you expect to use elsewhere in your code. For instance:
// filename: grokelation.jsdoc
/**
* #module grokelates
*/
/**
* #name Grokelate
* #memberof module:grokelates
* #description
* Here is the description of the grokelation process.
*
* #example
* var g = new Grokelate(opts);
*/
Then, when you wish to reference this new object elsewhere in your documentation, simply use its long name module:grokelates~Grokelate where you can consider the ~ glyph to mean "member of".
In your example above, you'd say {#link module:grokelates~Grokelate}.
I need to annotate some methods which are generated by Faktor-IPS. The most common case is the #Override-annotation, because I have additional interfaces or a base class I implement:
* Gibt den Wert des Attributs beschreibung zurueck.
*
* #generated
*/
#IpsAttribute(name = "beschreibung", kind = AttributeKind.CHANGEABLE, valueSetKind = ValueSetKind.AllValues)
#Override // <- manually added
public String getBeschreibung() {
return beschreibung;
}
Problem is, that the additional annotation is removed by the code generator of Faktor-IPS.
I know about the special tags to use in the class-comment ( "#implements a.b.c.MyInterface" ) to keep the class implement the interface a.b.c.MyInterface - is there something similar for annotations, especially on generated methods?
Faktor-IPS uses the JMerge tool created by the Eclipse EMF project to combine generated and handwritten code. There is a (German) description of the ways you can control how the code is merged at https://www.faktorzehn.org/de/en/dokumentation/manuelle-anpassungen-des-generieten-codes/.
To keep additional annotations while still letting the code generator update the rest of the code, add the Javadoc tag (inside the Javadoc, not an annotation, although also beginning with '#') '#customizedAnnotations ADDED'.
If you have certain annotations that you want to add in many places, that workaround is too much work, so Faktor-IPS allows you to define a list of annotations that will never be removed in the .ipsproject generator setting 'retainAnnotations': just add 'Override' there and any '#Override' annotation you manually place won't be removed by the generator.
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.
This is another of those utilities where every blogger\tutor assumes we all know what it is, therefore they never bother to explain what it actually does. They just go on to use it in their examples, believing we all know what's going on.
From how people use or refer to render(), it would suggest that it displays content(eg: view content) but if this is so, then why do we use echo to actually display it's content?
Other uses suggests that it formats content, as used in form-decorators where internally we employ sprintf() to inject variables into strings.
So what does render() do in cases like Zend_View, Zend_Layout, etc? Can someone please explain it's workings on a fundamental level(under the hood). Thanks.
It loads a view script and outputs it as a string.
Simplifying a bit, Zend_View takes a view script file (like index.phtml) and includes it internally to produce the HTML output. By using the render() method, it's possible to take an additional view script (like maybe nav.phtml) and output it inside your parent view script. The idea is to render elements that are repeated on many pages just one single time instead of repeating the same HTML over and over again.
The code for the render method can be found in the Zend_View_Abstract class and is the following:
/**
* Processes a view script and returns the output.
*
* #param string $name The script name to process.
* #return string The script output.
*/
public function render($name)
{
// find the script file name using the parent private method
$this->_file = $this->_script($name);
unset($name); // remove $name from local scope
ob_start();
$this->_run($this->_file);
return $this->_filter(ob_get_clean()); // filter output
}
The implementation of the _run() method can be found in the class Zend_View and is the following:
/**
* Includes the view script in a scope with only public $this variables.
*
* #param string The view script to execute.
*/
protected function _run()
{
if ($this->_useViewStream && $this->useStreamWrapper()) {
include 'zend.view://' . func_get_arg(0);
} else {
include func_get_arg(0);
}
}
As you can see, render() takes a view script name, resolves its file name, initiates output buffering, includes the view script file (this is what the _run() method does internally), then passes the output through optional filters and finally returns the generated string.
The neat thing about it is that it retains the properties (variables) of the view object it is called from (because it's the same Zend_View object, just with a different view script loaded). In this respect, it differs from the partial() method, which has its own variable scope and you can pass variables into it (making it useful for rendering smaller elements, such as single rows of data when you foreach over a dataset).
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