[conf] Add annotations for documenting proxy configuration settings (a…

…pache#3106)

* [conf] Add annotations for documenting proxy configuration settings

*Motivation*

It is non-trivial to keep configuration in-sync between code and configuration file.
The change is introducing documentation related annotations. So the annotations can be used
for generating proxy configuration file.

pulsar-broker-common/src/main/java/org/apache/pulsar/common/configuration/Category.java

@@ -0,0 +1,33 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.pulsar.common.configuration;
+
+/**
+ * Setting Category.
+ */
+public @interface Category {
+
+    /**
+     * Description of the category.
+     *
+     * @return description of the category
+     */
+    String description() default "";
+
+}

pulsar-broker-common/src/main/java/org/apache/pulsar/common/configuration/FieldContext.java

@@ -37,33 +37,55 @@
      * 
      * @return true if attribute is required else returns false
      */
-    public boolean required() default false;
+    boolean required() default false;
 
     /**
      * binds numeric value's lower bound
      * 
      * @return minimum value of the field
      */
-    public long minValue() default Long.MIN_VALUE;
+    long minValue() default Long.MIN_VALUE;
 
     /**
      * binds numeric value's upper bound
      * 
      * @return maximum value of the field
      */
-    public long maxValue() default Long.MAX_VALUE;
+    long maxValue() default Long.MAX_VALUE;
 
     /**
      * binds character length of text
      * 
      * @return character length of field
      */
-    public int maxCharLength() default Integer.MAX_VALUE;
+    int maxCharLength() default Integer.MAX_VALUE;
 
     /**
      * allow field to be updated dynamically
      * 
      * @return
      */
-    public boolean dynamic() default false;
+    boolean dynamic() default false;
+
+    /**
+     * Category to group settings.
+     *
+     * @return category name
+     */
+    String category() default "";
+
+    /**
+     * Documentation of the settings.
+     *
+     * @return the documentation of the settings.
+     */
+    String doc() default "";
+
+    /**
+     * Whether the setting is deprecated or not.
+     *
+     * @return true if the setting is deprecated, otherwise false.
+     */
+    boolean deprecated() default false;
+
 }

pulsar-broker-common/src/main/java/org/apache/pulsar/common/configuration/PropertiesContext.java

@@ -0,0 +1,33 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.pulsar.common.configuration;
+
+/**
+ * Documentation Annotation for Properties.
+ */
+public @interface PropertiesContext {
+
+    /**
+     * Return list of properties.
+     *
+     * @return list of fields
+     */
+    PropertyContext[] properties();
+
+}

pulsar-broker-common/src/main/java/org/apache/pulsar/common/configuration/PropertyContext.java

@@ -0,0 +1,40 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.pulsar.common.configuration;
+
+/**
+ * Annotation for a given property.
+ */
+public @interface PropertyContext {
+
+    /**
+     * Key of the property.
+     *
+     * @return key of the property.
+     */
+    String key();
+
+    /**
+     * Documentation of the property.
+     *
+     * @return documentation of the property.
+     */
+    FieldContext doc();
+
+}