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
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.
What I'm trying to achieve is that if i have 2 components nodes :
component1
clientlib
component1.js
component2
clientlib
component2.js
and i drag them into page1, then when page1 is generated, only component1.js and component2.js will be loaded when navigating to page1 .
One approach i saw is to use custom Tag Library as described here : http://www.icidigital.com/blog/best-approaches-clientlibs-aem-part-3/
I have two questions :
1) is there an existing feature in AEM to do this ?
2) if not, what is the easiest way to create such custom Tag Library ?
EDIT:
Assume that there is no ability to just include all component clientLibs, rather load only those that are added to the page.
There is no built in feature to do this. Although I've heard that the clientlib infrastructure is being looked at for a re-write so I'm optimistic that something like this will be added in the future.
We have, and I know other company have, created a "deferred script tag." Ours is a very simple tag that take a chunk of html like a clientlib include, add it to a unique list and then on an out call at the footer, spits it all out one after another.
Here's the core of a simple tag implementation that extends BodyTagSupport. Then in your footer grab the attribute and write it out.
public int doEndTag() throws JspException {
SlingHttpServletRequest request = (SlingHttpServletRequest)pageContext.getAttribute("slingRequest");
Set<String> delayed = (Set<String>)request.getAttribute(DELAYED_INCLUDE);
if(delayed == null){
delayed = new HashSet<String>();
}
if(StringUtils.isNotBlank(this.bodyContent.getString())){
delayed.add(this.bodyContent.getString().trim());
}
request.setAttribute(DELAYED_INCLUDE, delayed);
return EVAL_PAGE;
}
Theoretically the possible way of doing is to write script in your page component/abstract page component that does something like this -
Step1 : String path = currentPage.getPath()
Step2 : Query this path for components (one way is to have a master list do a contains clause on sling:resourceType)
Step 3: User resource resolver to resolve the resourceType in Step 3, this will give you resource under your apps.
Step 4: From the above resource get the sub-resource with primary type as cq:ClientLibraryFolder
Step 5: from the client libs resource in Step 4 get the categories and include the JS from them
you could actually write a model to adapt a component resource to a clientLibrary to actually clean the code.
Let me know if you need actual code, I can write that in my free time.
I have spent days on this one so I have put my hand up. I am implementing tags in my own component and have followed Elin's instructions on the Joomla site to the letter (27 July 2013). I can get the new tags to save in the TAGS table correctly, but not the UCM or TAG MAP tables as all the standard components do.
I have traced the code all the way through, and compared to the com_contacts, and cannot for the life of me see any difference in my component.
Where should I be looking for where the code updates the other two tables? I know this will end in an embarrassing answer but I am happy to look foolish.
My table does not have meta fields, but I have manually fudged the metadata array in the $data array. Any help is appreciated.
Instructions:http://docs.joomla.org/J3.1:Using_Tags_in_an_Extension
After many days of extra frustration I discovered that for my component I had to include the archived information into my table class, that is not supposed to be required any more.
Add a property
/**
* Indicator that the tags have been changed
*
* #var JHelperTags
* #since 3.1
*/
protected $tagsHelper = null;
This property helps to manage change in tags.
Modify your constructor
Follow this example to modify your consructor which provides substantial reduction in duplicate code.
$this->tagsHelper = new JHelperTags();
$this->tagsHelper->typeAlias = 'com_contact.contact';
Modify your store() method
Management of tagging and associated data is largely handled through the store() method. This provides maximum flexibility for the handling of tags across many extensions.
If you don't have a store() method you will need to add one. The assumption is that tables will inherit from JTable.
The handling involves preStoreProcess(), a call to the parent store() method, and then a postStoreProcess().
$this->tagsHelper->preStoreProcess($this);
$result = parent::store($updateNulls);
return $result && $this->tagsHelper->postStoreProcess($this);
SpecFlow is great - and it helps us very much to do proper integration testing.
One thing I was wondering is whether there's a way to tell SpecFlow to add additional NUnit attributes to the test class it creates in the feature code-behind file.
Right now, my test class gets generated something like this:
[System.CodeDom.Compiler.GeneratedCodeAttribute("TechTalk.SpecFlow", "1.8.1.0")]
[System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
[NUnit.Framework.TestFixtureAttribute()]
[NUnit.Framework.DescriptionAttribute("Some action description here")]
public partial class MySampleFeature
{
......
}
Is there any way in SpecFlow to tell it to add an additional NUnit attribute to define the category of the test - like this:
[System.CodeDom.Compiler.GeneratedCodeAttribute("TechTalk.SpecFlow", "1.8.1.0")]
[System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
[NUnit.Framework.TestFixtureAttribute()]
[NUnit.Framework.DescriptionAttribute("Some action description here")]
[NUnit.Framework.Category("LongRunningTests")] <== add this "Category" attribute
public partial class MySampleFeature
{
......
}
Adding this manually to the generated code-behind is wasteful - next time SpecFlow re-generates that code-behind, I have to remember doing it again (and chances are, I'll forget).
And if that capability is not yet present in SpecFlow - how to petition for this to be added? :-)
In fact the NUnit.Framework.Category attribute is already supported if you use tags (look for the tags section) on your feature or scenarios. So if you write
#LongRunningTests
Feature: MySampleFeature
it will generate the proper Category attribute.
However if you want to have additional custom attributes you need to write a custom generator provider with implementing the IUnitTestGeneratorProvider interface and register with the unitTestProvider's generatorProvider attribute in your config's specflow section.
You can find the source of the built in implementations at github.
To add to #nemesv's good answer, once you've added:
#LongRunningTests
Feature: MySampleFeature
To execute from the console, do this:
nunit3-console.exe myTests.dll --where "cat==LongRunningTests"