Merge pull request #1453 from smartdevicelink/feature/issue_1448_generate_deprecated_javadoc

Generate @deprecated annotation in JavaDocs when applicable

Author: Robert Henigan

generator/templates/base_template.java

@@ -63,23 +63,21 @@
  *      <td>{%- for d in param.description %}{{d}}{%- endfor %}</td>
  *      <td>{%- if param.mandatory is eq true %}Y{%- else %}N{%- endif %}</td>
  *      <td>{%- for k in param.values %}{{ '{' if loop.first}}"{{k}}": {{param.values[k]}}{{ ', ' if not loop.last else  '}'}}{%- endfor %}</td>
- *      <td>{%- if param.since is defined %}SmartDeviceLink {{param.since}}{%- endif %}</td>
+        {%- if param.since is defined and param.since is not none %}{% set see, deprecated, since, history, spacing = param.see, param.deprecated, param.since, param.history, ' *         ' %}
+ *      <td>
+        {%- include "javadoc_version_info.java" %}
+ *      </td>
+        {%- else %}
+ *      <td></td>
+        {%- endif %}
  *  </tr>
  {%- endfor %}
  * </table>
  {%- endif %}
  {%- if description is defined and (see is defined or since is defined) %}
  *
- {%- endif %}
- {%- if deprecated is not none %}
- * @deprecated
- {%- endif %}
- {%- if see is defined %}
- * @see {{see}}
- {%- endif %}
- {%- if since is defined %}
- * @since SmartDeviceLink {{since}}
- {%- endif %}
+ {%- endif %}{% set prefix = ' * ' %}
+ {%- include "javadoc_version_info.java" %}
  */
 {%- endif %}
 {%- if deprecated is not none %}

generator/templates/enum_template.java

@@ -10,13 +10,8 @@ public enum {{class_name}} {
      {%- endfor %}{% endif -%}
      {%- if param.description is defined and (param.since is defined or param.see is defined) %}
      *
-     {%- endif %}
-     {%- if param.since is defined %}
-     * @since SmartDeviceLink {{param.since}}
-     {%- endif %}
-     {%- if param.see is defined %}
-     * @see {{param.see}}
-     {%- endif %}
+     {%- endif %}{% set see, deprecated, since, history, spacing, prefix = param.see, param.deprecated, param.since, param.history, '    ', ' * ' %}
+     {%- include "javadoc_version_info.java" %}
      */
     {%- endif %}
     {%- if param.deprecated is defined %}

generator/templates/function_template.java

@@ -3,17 +3,8 @@
     {%- block params %}
     {%- if params is defined %}
     {%- for p in params %}
-    {%- if p.origin not in ('success', 'resultCode', 'info') or kind != "response" %}
-    {%- if p.see is defined or p.deprecated is not none %}
-    /**
-     {%- if p.deprecated is not none %}
-     * @deprecated
-     {%- endif %}
-     {%- if p.see is defined %}
-     * @see {{p.see}}
-     {%- endif %}
-     */
-    {%- endif %}
+    {%- if p.origin not in ('success', 'resultCode', 'info') or kind != "response" %}{% set see, deprecated, since, history, spacing, begin, end, prefix = p.see, p.deprecated, p.since, p.history, '    ', '/**', ' */', ' * ' %}
+    {%- include "javadoc_version_info.java" %}
     {%- if p.deprecated is not none %}
     @Deprecated
     {%- endif %}
@@ -37,6 +28,9 @@
      *
      {%- include "javadoc_template.java" %}
      */
+    {%- if p.deprecated is defined and p.deprecated is not none %}
+    @Deprecated
+    {%- endif %}
     public void set{{p.title}}({% if p.mandatory %}@NonNull {% endif %}{{p.return_type}} {{p.last}}) {
         setParameters({{p.key}}, {{p.last}});
     }
@@ -49,6 +43,9 @@
     {%- if p.SuppressWarnings is defined %}
     @SuppressWarnings("{{p.SuppressWarnings}}")
     {%- endif %}
+    {%- if p.deprecated is defined and p.deprecated is not none %}
+    @Deprecated
+    {%- endif %}
     public {{p.return_type}} get{{p.title}}() {
         {%- if p.return_type in ['String', 'Boolean', 'Integer'] %}
         return get{{p.return_type}}({{p.key}});

generator/templates/javadoc_return.java

@@ -10,7 +10,5 @@
      {%- endif %}
      {%- if p.values is defined and p.values %}
      * {%- for k in p.values %}{{ ' {' if loop.first}}"{{k}}": {{p.values[k]}}{{ ', ' if not loop.last else  '}'}}{%- endfor %}
-     {%- endif %}
-     {%- if p.since is defined %}
-     * @since SmartDeviceLink {{p.since}}
-     {%- endif %}
+     {%- endif %}{% set see, deprecated, since, history, spacing, prefix = p.see, p.deprecated, p.since, p.history, '    ', ' * ' %}
+     {%- include "javadoc_version_info.java" %}

generator/templates/javadoc_template.java

@@ -10,7 +10,5 @@
      {%- endif %}
      {%- if p.values is defined and p.values %}
      * {%- for k in p.values %}{{ ' {' if loop.first}}"{{k}}": {{p.values[k]}}{{ ', ' if not loop.last else  '}'}}{%- endfor %}
-     {%- endif %}
-     {%- if p.since is defined %}
-     * @since SmartDeviceLink {{p.since}}
-     {%- endif %}
+     {%- endif %}{% set see, deprecated, since, history, spacing, prefix = p.see, p.deprecated, p.since, p.history, '    ', ' * ' %}
+     {%- include "javadoc_version_info.java" %}

generator/templates/javadoc_version_info.java

@@ -0,0 +1,19 @@
+{%- if since is defined and since is not none %}
+{%- if begin is defined %}
+{{spacing}}{{begin}}
+{%- endif %}
+{%- if deprecated is defined and deprecated is not none %}
+{{spacing}}{{prefix}}@since SmartDeviceLink {{history[0].since}}
+{{spacing}}{{prefix}}@deprecated in SmartDeviceLink {{since}}
+{%- elif history is defined and history is not none %}
+{{spacing}}{{prefix}}@since SmartDeviceLink {{history[0].since}}
+{%- else %}
+{{spacing}}{{prefix}}@since SmartDeviceLink {{since}}
+{%- endif %}
+{%- if see is defined %}
+{{spacing}}{{prefix}}@see {{see}}
+{%- endif %}
+{%- if end is defined %}
+{{spacing}}{{end}}
+{%- endif %}
+{%- endif %}

generator/templates/struct_template.java

@@ -2,17 +2,8 @@
 
     {%- block params %}
     {%- if params is defined %}
-    {%- for p in params %}
-    {%- if p.see is defined or p.deprecated is not none %}
-    /**
-     {%- if p.deprecated is not none %}
-     * @deprecated
-     {%- endif %}
-     {%- if p.see is defined %}
-     * @see {{p.see}}
-     {%- endif %}
-     */
-    {%- endif %}
+    {%- for p in params %}{% set see, deprecated, since, history, spacing, begin, end, prefix = p.see, p.deprecated, p.since, p.history, '    ', '/**', ' */', ' * ' %}
+    {%- include "javadoc_version_info.java" %}
     {%- if p.deprecated is not none %}
     @Deprecated
     {%- endif %}
@@ -33,6 +24,9 @@
      *
      {%- include "javadoc_template.java" %}
      */
+    {%- if p.deprecated is defined and p.deprecated is not none %}
+    @Deprecated
+    {%- endif %}
     public void set{{p.title}}({% if p.mandatory %}@NonNull {% endif %}{{p.return_type}} {{p.last}}) {
         setValue({{p.key}}, {{p.last}});
     }
@@ -45,6 +39,9 @@
     {%- if p.SuppressWarnings is defined %}
     @SuppressWarnings("{{p.SuppressWarnings}}")
     {%- endif %}
+    {%- if p.deprecated is defined and p.deprecated is not none %}
+    @Deprecated
+    {%- endif %}
     public {{p.return_type}} get{{p.title}}() {
         {%- if p.return_type in ['String', 'Boolean', 'Integer'] %}
         return get{{p.return_type}}({{p.key}});

generator/transformers/enums_producer.py

@@ -59,6 +59,7 @@ def transform(self, item: Enum) -> dict:
         render['params'] = params
         render['since'] = item.since
         render['deprecated'] = item.deprecated
+        render['history'] = item.history
 
         description = self.extract_description(item.description)
         if description:
@@ -81,6 +82,8 @@ def extract_param(self, param: EnumElement, kind):
             d['since'] = param.since
         if getattr(param, 'deprecated', None):
             d['deprecated'] = param.deprecated
+        if getattr(param, 'history', None):
+            d['history'] = param.history
         if getattr(param, 'description', None):
             d['description'] = textwrap.wrap(self.extract_description(param.description), 90)
         Params = namedtuple('Params', sorted(d))

generator/transformers/functions_producer.py

@@ -73,6 +73,7 @@ def transform(self, item: Function) -> dict:
         render['extends_class'] = extends_class
         render['since'] = item.since
         render['deprecated'] = item.deprecated
+        render['history'] = item.history
 
         description = self.extract_description(item.description)
         if description:
@@ -118,6 +119,7 @@ def extract_param(self, param: Param):
         if param.since:
             p['since'] = param.since
         p['deprecated'] = param.deprecated
+        p['history'] = param.history
         p['origin'] = param.origin
         p['values'] = self.extract_values(param)
         d = self.extract_description(param.description)

generator/transformers/structs_producer.py

@@ -58,6 +58,7 @@ def transform(self, item: Struct) -> dict:
         render['imports'] = imports
         render['deprecated'] = item.deprecated
         render['since'] = item.since
+        render['history'] = item.history
 
         description = self.extract_description(item.description)
         if description:
@@ -104,6 +105,7 @@ def extract_param(self, param: Param):
         if param.since:
             p['since'] = param.since
         p['deprecated'] = param.deprecated
+        p['history'] = param.history
         p['origin'] = param.origin
         p['values'] = self.extract_values(param)
         d = self.extract_description(param.description)