Gendoc/developerResources/PropertiesExample

Presentation

The goal of the example is creating a tag named "Properties" which allows the registration of parameters using properties file. The properties file will be referenced through an attribute named "path". This attribute would be able to contain reference to gendoc variables (${project_loc}, ${input_directory}....)

Contributing

Open a bug

first step is to create a new Bug categorized as an enhancement. In our example the created bug is : https://bugs.eclipse.org/bugs/show_bug.cgi?id=484129

Code

The code source of this example can be visible through these 2 gerrit contributions :

• https://git.eclipse.org/r/#/c/74976/
• https://git.eclipse.org/r/#/c/75143/

Global Idea

The good way to create a tag in gendoc is :

• create a handler (implements org.eclipse.gendoc.tags.ITagHandler) which analyze the tag
• create a service (extends org.eclipse.gendoc.services.AbstractService or implements org.eclipse.gendoc.services.IService) which will do business work

It is a common practice in gendoc to separate handlers and services

• Services can be overridden by developers so initial behavior can be changed
• It forces the developer to separate tha analysis of the tag and the business code

Tag Handler

• Fill the extension : org.eclipse.gendoc.tags to create new tag
  • the tag contains one attribute : "path" which is required and typed java.lang.String
  • reference a class you will create : org.eclipse.gendoc.tags.handlers.impl.properties.PropertiesTagHandler

Some mechanisms exist in gendoc to plug operation on tag analysis, to automatically get them our class inherits from org.eclipse.gendoc.tags.handlers.impl.AbstractServicesTagHandler

The methods to implement in PropertiesTagHandler.java are doRun and runAttributes. - doRun is the method call to run a tag. ie when the content of the tag is replaced by a new content. In the properties case we want to remove the content so we only have to return an empty String :

@Override public String doRun(ITag tag) throws GenDocException {

   super.doRun(tag);
   return "";

}