Projects:JavaDoc Improvements/Specs

Goal

This project objective is improving JavaDoc for generated entities and properties.

Functional Requirements

This project will not add new functional features.

Technical Specs

Project Tasks

This project tasks have been split in several issues.

• Add table and column information to getters and setters: 40837
• Add help to entity class, getters and setters: 41629
• Add deprecated tag to entity using Development Status AD property: 40836

Decisions Taken

Several technical decisions have been made in regards to this project.

• Added new functionality to add and remove help from ModelProvider model. After generation help it is removed from In-Memory model to keep memory size low as it is not being used after entity generation. This is due to ModelProvider's singleton design.
• String *\ is escaped from help messages because if it is inserted into the JavaDoc comments it breaks the code generated.
• Deprecated tag is added in development environment without publishing it. Methods deprecated by this tag get compiled so developers and teams can choose to remove or keep deprecation. If all teams choose to finally deprecate the method/class it gets pushed to CI.
• New Openbravo property hb.generate.deprecated.tags.on.properties has been added. If set to true it generates the corresponding deprecated tags for columns with Development Status set as Deprecated. This is useful for stopping the generation of deprecated methods and classes on CI.
• Deprecated tags get added to entities and properties from tables/columns that have property Development Status set to "Deprecated" in Application Dictionary. If a column is marked as deprecated, its setters/getters get marked as deprecated.
• Help messages are shown over properties. Getters setters are linked to properties in JavaDoc using @see.
• Help messages used in JavaDoc will not be interpreted as HTML. @literal JavaDoc tag wraps every help message to get rid of HTML interpretation.

Help over property:

    ...
    /**
    * {@literal An alert that has been raised.}
    */
    public static final String PROPERTY_ID = "id";
    /**
    * {@literal A Client is a company or a legal entity. You cannot share data between Clients.}
    */
    public static final String PROPERTY_CLIENT = "client";
    /**
    * {@literal An organization is a unit of your client or legal entity - examples are store, department. You can share data between organizations.}
    */
    public static final String PROPERTY_ORGANIZATION = "organization";
    /**
    * {@literal There are two methods of making records unavailable in the system: One is to delete the record, the other is to de-activate the record. 
A de-activated record is not available for selection, but available for reporting. There are two reasons for de-activating and not deleting records: 
(1) The system requires the record for auditing purposes.
(2) The record is referenced by other records. E.g., you cannot delete a Business Partner, if there are existing invoices for it. By de-activating the Business Partner you prevent it from being used in future transactions.}
    */
    public static final String PROPERTY_ACTIVE = "active";
 
...
 
    /**
     * Getter for property id 
     * (stored in column AD_Alert_ID in table AD_Alert)
     */
    public String getId() {
        return (String) get(PROPERTY_ID);
    }
	
    /**
     * Setter for property id 
     * (stored in column AD_Alert_ID in table AD_Alert)
     */
    public void setId(String id) {
        set(PROPERTY_ID, id);
    }
 
    /**
     * Getter for property client 
     * (stored in column AD_Client_ID in table AD_Alert)
     */
    public Client getClient() {
        return (Client) get(PROPERTY_CLIENT);
    }