Skip to content

Writing Javadocs

Jump to bottom
Vinay Gera edited this page Jan 25, 2024 · 2 revisions

Writing Javadocs For Client Library

Effective documentation is a cornerstone of software development, and JavaDoc stands out as a powerful tool for documenting Java code. JavaDoc, short for Java Documentation, allows developers to embed structured comments within their code, providing a comprehensive and easily accessible reference for both creators and consumers of the codebase. The benefits of adding quality JavaDocs extend beyond mere code explanation; they contribute to fostering collaboration, ensuring maintainability, and enhancing overall software quality. Here are some key advantages:

  • Improved Code Readability: JavaDocs provide a clear and concise description of classes, methods, and fields, enhancing code readability for developers who may be unfamiliar with the codebase.

  • Facilitates Collaboration: Quality JavaDocs serve as a communication medium, helping team members understand the purpose and functionality of different code components. This fosters collaboration by reducing the learning curve for new contributors and aiding in effective teamwork.

  • Enhanced Code Navigation: Integrated development environments (IDEs) leverage JavaDoc comments to provide context-aware tooltips and documentation pop-ups. This feature aids developers in understanding code context without navigating away from their current workflow.

  • Supports Testing and Debugging: JavaDocs can include information on parameters, return values, and exceptions, providing valuable insights for testing and debugging. Developers can better understand the expected behavior of methods, helping them write effective test cases.

Instructions to update Javadocs

You will need to follow following steps to update Javadocs:

  • Update package info docs
  • Update class level documentation of builders, clients and models in your SDKs
  • Note: Use JDK 21 to compile your SDK's javadoc as well and fix any compile warnings/errors that come up as part of your PRs. This will ensure our Javadocs are compatible with next Java LTS release (JDK 21)

Estimated effort per library = 4-5 dev days.

Update Package Info Docs

Upgrade the Java library's package info documentation for improved user understanding. Begin with a brief service introduction, followed by a focused getting started section covering authentication and client instantiation. Dive into key API details, providing clear usage instructions with illustrative examples. This concise update ensures users can swiftly navigate and utilize our Java library effectively, enhancing overall user experience. Your attention to detail in this documentation refinement is greatly valued.

Example: Azure App Configuration:

The below sample uses azure-data-appconfiguration as an example, which you can follow for your library.

/**
 * // Instroduce the service
 *
 * <p><a href="https://learn.microsoft.com/azure/azure-app-configuration/">Azure App Configuration Service</a>
 * is a managed service provided by Microsoft Azure that allows developers to centralize configuration settings for
 * their applications. With App Configuration, developers can store and manage application settings, feature flags,
 * and other configuration data in one central location. This simplifies the management of configuration settings and
 * makes it easy to update configuration values for multiple applications.</p>
 *
 * // Introduce the library
 *
 * <p>The Azure App Configuration library is a client library that provides Java developers with a simple and
 * easy-to-use interface for accessing and using the Azure App Configuration Service. This library allows developers to
 * easily manage their application's configuration settings, feature flags, and other configuration data stored in the
 * Azure App Configuration Service.
 * </p>
 *
 * // Add a Getting Started section that covers key steps user needs to follow to start using the clients via the library.
 *
 * <h2>Getting Started</h2>
 *
 * <p>In order to interact with the App Configuration service you'll need to create an instance of the Configuration
 * Client class. To make this possible you'll need the connection string of the configuration store. Alternatively,
 * you can use AAD authentication via
 * <a href="https://learn.microsoft.com/java/api/overview/azure/identity-readme?view=azure-java-stable"> Azure Identity</a>
 * to connect to the service.</p>
 * <ol>
 *   <li>Connection string, see {@link com.azure.data.appconfiguration.ConfigurationClientBuilder#connectionString(java.lang.String) connectionString}.</li>
 *   <li>Azure Active Directory, see {@link com.azure.data.appconfiguration.ConfigurationClientBuilder#credential(com.azure.core.credential.TokenCredential) TokenCredential}.</li>
 * </ol>
 *
 * // Add Samples to construct the async and sync client.
 *
 * <p><strong>Sample: Construct Asynchronous Configuration Client with Connection String</strong></p>
 *
 * <p>The following code sample demonstrates the creation of a {@link com.azure.data.appconfiguration.ConfigurationAsyncClient},
 * using the {@link com.azure.data.appconfiguration.ConfigurationClientBuilder} to configure it with a connection
 * string.</p>
 *
 * <!-- src_embed com.azure.data.applicationconfig.async.configurationclient.instantiation  -->
 * <pre>
 * ConfigurationAsyncClient configurationAsyncClient = new ConfigurationClientBuilder&#40;&#41;
 *     .connectionString&#40;connectionString&#41;
 *     .buildAsyncClient&#40;&#41;;
 * </pre>
 * <!-- end com.azure.data.applicationconfig.async.configurationclient.instantiation  -->
 *
 * <p><strong>Sample: Construct Synchronous Configuration Client with Connection String</strong></p>
 *
 * <p>The following code sample demonstrates the creation of a {@link com.azure.data.appconfiguration.ConfigurationClient},
 * using the {@link com.azure.data.appconfiguration.ConfigurationClientBuilder} to configure it with a connection
 * string.</p>
 *
 * <!-- src_embed com.azure.data.applicationconfig.configurationclient.instantiation -->
 * <pre>
 * ConfigurationClient configurationClient = new ConfigurationClientBuilder&#40;&#41;
 *     .connectionString&#40;connectionString&#41;
 *     .buildClient&#40;&#41;;
 * </pre>
 * <!-- end com.azure.data.applicationconfig.configurationclient.instantiation -->
 *
 * <p>App Configuration support multiple operations, such as create, update, retrieve, and delete a configuration setting.
 * See methods in client level class below to explore all capabilities that library provides.</p>
 *
 * <p>For more configuration setting types, see
 * {@link com.azure.data.appconfiguration.models.FeatureFlagConfigurationSetting} and
 * {@link com.azure.data.appconfiguration.models.SecretReferenceConfigurationSetting}.</p>
 *
 * <br/>
 *
 * <hr/>
 *
 * // Cover key API scenarios and their usage samples below with a brief description
 *
 * <h2>Add Configuration Setting</h2>
 *
 * <p>The {@link com.azure.data.appconfiguration.ConfigurationClient#addConfigurationSetting(com.azure.data.appconfiguration.models.ConfigurationSetting) addConfigurationSetting}
 * method can be used to add a configuration setting in the Azure App Configuration.</p>
 *
 * <p>The sample below shows how to add a setting with the key "prodDBConnection", label "westUS" and value "db_connection" using {@link com.azure.data.appconfiguration.ConfigurationClient}.</p>
 *
 * <!-- src_embed com.azure.data.appconfiguration.ConfigurationClient.addConfigurationSetting#ConfigurationSetting -->
 * <pre>
 * ConfigurationSetting setting = configurationClient.addConfigurationSetting&#40;new ConfigurationSetting&#40;&#41;
 *     .setKey&#40;&quot;prodDBConnection&quot;&#41;
 *     .setLabel&#40;&quot;westUS&quot;&#41;
 *     .setValue&#40;&quot;db_connection&quot;&#41;&#41;;
 * System.out.printf&#40;&quot;Key: %s, Label: %s, Value: %s&quot;, setting.getKey&#40;&#41;, setting.getLabel&#40;&#41;, setting.getValue&#40;&#41;&#41;;
 * </pre>
 * <!-- end com.azure.data.appconfiguration.ConfigurationClient.addConfigurationSetting#ConfigurationSetting -->
 *
 * <p><strong>Note:</strong> For asynchronous sample, refer to {@link com.azure.data.appconfiguration.ConfigurationAsyncClient}.</p>
 *
 * <br/>
 *
 * <hr/>
 *
 * // Cover more key scenarios here in the same pattern like above for your library. 
 *
 * // Add see tags to client class, builder class and any other relevant classes.
 *
 * @see com.azure.data.appconfiguration.ConfigurationClientBuilder
 * @see com.azure.data.appconfiguration.ConfigurationAsyncClient
 * @see com.azure.data.appconfiguration.ConfigurationClient
 * @see com.azure.data.appconfiguration.models.ConfigurationSetting
 */

Update Client Level Class Docs

Enhance the Java library's client class-level documentation for improved user understanding. Introduce the client class briefly, provide a sample for instantiation instructions, and detail key APIs along with concise usage guidelines and examples. This concise update streamlines user guidance, facilitating a more effective utilization of our Java library. Your attention to detail in refining these client class docs is appreciated.

Example: Azure App Configuration:

The below sample uses azure-data-appconfiguration as an example for ConfigurationClientClass, which you can follow for your library.

/**
 *
 * // Introduce the client class.
 *
 * <p>This class provides a client that contains all the operations for {@link ConfigurationSetting ConfigurationSettings},
 * {@link FeatureFlagConfigurationSetting FeatureFlagConfigurationSetting} or
 * {@link SecretReferenceConfigurationSetting SecretReferenceConfigurationSetting} in Azure App Configuration Store.
 * Operations allowed by the client are adding, retrieving, deleting, set read-only status ConfigurationSettings, and
 * listing settings or revision of a setting based on a {@link SettingSelector filter}.</p>
 *
 * <p>Additionally, this class allows to add an external synchronization token to ensure service requests receive
 * up-to-date values. Use the {@link #updateSyncToken(String) updateSyncToken} method.</p>
 *
 * // Cover Instructions to get started with the client class, cover authentication and any other requirements user
 * // has to follow to instantiate the client.
 *
 * <h2>Getting Started</h2>
 *
 * <p>In order to interact with the App Configuration service you'll need to create an instance of the
 * {@link com.azure.data.appconfiguration.ConfigurationClient} class. To make this possible you'll need the connection
 * string of the configuration store. Alternatively, you can use AAD authentication via
 * <a href="https://learn.microsoft.com/java/api/overview/azure/identity-readme?view=azure-java-stable"> Azure Identity</a>
 * to connect to the service.</p>
 * <ol>
 *   <li>Connection string, see {@link com.azure.data.appconfiguration.ConfigurationClientBuilder#connectionString(java.lang.String) connectionString}.</li>
 *   <li>Azure Active Directory, see {@link com.azure.data.appconfiguration.ConfigurationClientBuilder#credential(com.azure.core.credential.TokenCredential) TokenCredential}.</li>
 * </ol>
 *
 * <p><strong>Instantiating a synchronous Configuration Client</strong></p>
 *
 * <!-- src_embed com.azure.data.applicationconfig.configurationclient.instantiation -->
 * <pre>
 * ConfigurationClient configurationClient = new ConfigurationClientBuilder&#40;&#41;
 *     .connectionString&#40;connectionString&#41;
 *     .buildClient&#40;&#41;;
 * </pre>
 * <!-- end com.azure.data.applicationconfig.configurationclient.instantiation -->
 *
 * <p>View {@link ConfigurationClientBuilder this} for additional ways to construct the client.</p>
 *
 * <p>App Configuration support multiple operations, such as create, update, retrieve, and delete a configuration setting.
 * See methods in client level class below to explore all capabilities that library provides.</p>
 *
 * <p>For more configuration setting types, see
 * {@link com.azure.data.appconfiguration.models.FeatureFlagConfigurationSetting} and
 * {@link com.azure.data.appconfiguration.models.SecretReferenceConfigurationSetting}.</p>
 *
 * <br/>
 *
 * <hr/>
 *
 * // Optionally Cover Key Usage/API scenarios here or point to package info docs where they are already covered.
 *
 * <h2>Add Configuration Setting</h2>
 *
 * <p>The {@link com.azure.data.appconfiguration.ConfigurationClient#addConfigurationSetting(ConfigurationSetting)}
 * method can be used to add a configuration setting in the Azure App Configuration.</p>
 *
 * <p>The sample below shows how to add a setting with the key "prodDBConnection", label "westUS" and value
 * "db_connection" using {@link com.azure.data.appconfiguration.ConfigurationClient}.</p>
 *
 * <!-- src_embed com.azure.data.appconfiguration.ConfigurationClient.addConfigurationSetting#ConfigurationSetting -->
 * <pre>
 * ConfigurationSetting setting = configurationClient.addConfigurationSetting&#40;new ConfigurationSetting&#40;&#41;
 *     .setKey&#40;&quot;prodDBConnection&quot;&#41;
 *     .setLabel&#40;&quot;westUS&quot;&#41;
 *     .setValue&#40;&quot;db_connection&quot;&#41;&#41;;
 * System.out.printf&#40;&quot;Key: %s, Label: %s, Value: %s&quot;, setting.getKey&#40;&#41;, setting.getLabel&#40;&#41;, setting.getValue&#40;&#41;&#41;;
 * </pre>
 * <!-- end com.azure.data.appconfiguration.ConfigurationClient.addConfigurationSetting#ConfigurationSetting -->
 *
 * <p><strong>Note:</strong> For asynchronous sample, refer to {@link com.azure.data.appconfiguration.ConfigurationAsyncClient}.</p>
 *
 * <br/>
 *
 * // Add see tags to relevant classes and the builder.
 *
 * @see ConfigurationClientBuilder
 * @see ConfigurationSetting
 */

More References to follow

Identity Package level Javadoc Identity Class level Javadoc Identity Builder level Javadoc

Client Library

User Guides

Extension Points

Contributor Guides

Management Library

User Guides

Contributor Guides

Spring Cloud Azure

Clone this wiki locally