[Discussion] Conventions for fluent model Javadocs

[jianghaolu]

This is a living discussion for the Javadoc conventions. Please feel free to comment and we will update the templates when appropriate.

License header

Copyright (c) Microsoft Corporation. All rights reserved.
Licensed under the MIT License. See License.txt in the project root for license information.

Models

Pet

/**
 * An immutable client-side representation of an Azure pet.
 */
public interface Pet {

Pet.DefinitionBlank

/**
 * A Pet definition allowing region to be set.
 */
public interface DefinitionBlank extends GroupableResource.DefinitionWithRegion<DefinitionWithGroup> {

Pet.DefinitionWithBreed

/**
 * A Pet definition allowing breed to be set.
 */
public interface DefinitionWithBreed {
    /**
     * TBD
     *
     * @param breed the breed to specify
     * @return the next stage of definition
     */ 
    DefinitionCreatable withBreed(String breed) {

Pet.DefinitionCreatable

/**
 * A Pet definition with sufficient inputs to create a new pet in the cloud, but exposing additional optional inputs to specify.
 */
public interface DefinitionCreatable
        extends 
    Creatable<Pet>,
    Resource.DefinitionWithTags<DefinitionCreatable>, ... {  {

Pet.Update

/**
 * The template for a pet update operation, containing all the settings that can be modified.
 */
public interface Update
        extends
    Appliable<Pet>,
    Resource.UpdateWithTags<Update>, ... {

Collections (Operations)

Pets

/**
 * Entry point to pet management API.
 */
public interface Pets {

Resource manager

PetStore Manager

/**
 * Entry point to Azure petstore resource management.
 */
public final class PetstoreManager {
    /**
     * Get a Configurable instance that can be used to create PetstoreManager with optional configuration.
     *
     * @return Configurable
     */
    public static Configurable configure() {
      ...
    }

    /**
     * Creates an instance of PetstoreManager that exposes Petstore resource management API entry points.
     *
     * @param credentials the credentials to use
     * @param subscriptionId the subscription
     * @return the PetstoreManager
     */
    public static ComputeManager authenticate(ServiceClientCredentials credentials, String subscriptionId) {
     ....
    }

    /**
     * Creates an instance of PetstoreManager that exposes Petsore resource management API entry points.
     *
     * @param restClient the RestClient to be used for API calls.
     * @param subscriptionId the subscription
     * @return the PetstoreManager
     */
    public static PetstoreManager authenticate(RestClient restClient, String subscriptionId) {
        ...
    }

    public interface Configurable extends AzureConfigurable<Configurable> {
        /**
         * Creates an instance of PetstoreManager that exposes Petstore resource management API entry points.
         *
         * @param credentials the credentials to use
         * @param subscriptionId the subscription
         * @return the PetstoreManager
         */
        PetstoreManager authenticate(ServiceClientCredentials credentials, String subscriptionId);
    }

    ....

    /**
     * @return the pet resource management API entry point
     */
    public Pets pets() {
        ....
    }

}

[martinsawicki]

public interface Update ...

will always

... extends Appliable<Pet>, Resource.UpdateWithTags<Update>, ...

[martinsawicki]

likewise:

interface DefinitionCreatable extends 
  Creatable<Pet>,
  Resource.DefinitionWithTags<DefinitionCreatable>, ... { 

[jianghaolu]

Updated.
BTW, this doc focuses mostly on the comments - as we are marching across the javadocs in all the classes, it's nice to have a convention upfront to follow than to make tons of "address code review feedbacks" commits later.

[anuchandy]

The comment pattern we follow for type representing a resource is:

An immutable client-side representation of an Azure <resource-name>

e.g. Pet

/**
 * An immutable client-side representation of an Azure pet.
 */
public interface Pet {

For a resource collection, it is:

Entry point to <resource-name> management API.

e.g. Pets

/**
 * Entry point to pet management API.
 */
public interface Pets  {

[anuchandy]

It will be good to add javadoc convention we follow for Manager types. For example:

/**
 * Entry point to Azure petstore resource management.
 */
public final class PetstoreManager {
    /**
     * Get a Configurable instance that can be used to create PetstoreManager with optional configuration.
     *
     * @return Configurable
     */
    public static Configurable configure() {
      ...
    }

    /**
     * Creates an instance of PetstoreManager that exposes Petstore resource management API entry points.
     *
     * @param credentials the credentials to use
     * @param subscriptionId the subscription
     * @return the PetstoreManager
     */
    public static ComputeManager authenticate(ServiceClientCredentials credentials, String subscriptionId) {
     ....
    }

    /**
     * Creates an instance of PetstoreManager that exposes Petsore resource management API entry points.
     *
     * @param restClient the RestClient to be used for API calls.
     * @param subscriptionId the subscription
     * @return the PetstoreManager
     */
    public static PetstoreManager authenticate(RestClient restClient, String subscriptionId) {
        ...
    }

    public interface Configurable extends AzureConfigurable<Configurable> {
        /**
         * Creates an instance of PetstoreManager that exposes Petstore resource management API entry points.
         *
         * @param credentials the credentials to use
         * @param subscriptionId the subscription
         * @return the PetstoreManager
         */
        PetstoreManager authenticate(ServiceClientCredentials credentials, String subscriptionId);
    }

    ....

    /**
     * @return the pet resource management API entry point
     */
    public Pets pets() {
        ....
    }

}

[jianghaolu]

Great! updated.

[anuchandy]

Below is copied from the PR comment #730, can we include this as well?

1. Getters whose doc can be simply put as one line – use simply @return
2. Getters whose doc is complicated and we want to elaborate – use block comment. An example: https://github.com/Azure/azure-sdk-for-java/blob/master/azure-mgmt-compute/src/main/java/com/microsoft/azure/management/compute/VirtualMachine.java#L84.
3. Setters will always use block comment and are explained in detail so that we don't get strangled. For simple ones we can something similar to: https://github.com/Azure/azure-sdk-for-java/blob/master/azure-mgmt-resources/src/main/java/com/microsoft/azure/management/resources/fluentcore/arm/models/GroupableResource.java#L21.

[martinsawicki]

regarding #2 -- something tells me javadocs should not be in the business of explaining how Azure works and what the recommended Azure usage practices are. That documentation I think belongs in Azure, not in a language-specific Javadoc. In that light, I think that Javadoc should just say:

@return a reference to the availability set an Azure virtual machine associated with.

(speaking of which - we may want to think about whether we could/should avoid returning SubResources in such reference situations but instead return an actual object, i.e. AvailabilitySet in this case...)

[jianghaolu]

Beta2 released.