Include the best practice for documenting a Ballerina record in the style guide

[Nipuna Fernando]

Description

ATM, the style guide does not specify what the best practice is for documenting a record: https://ballerina.io/learn/style-guide/annotations-documentation-and-comments/#documentation. Currently, there are two approaches to document a record.

1. Attach the documentation at the top of the type.

# Represents a user.
#
# + id - id of the user
# + name - name of the user  
# + isMember - whether the user is a member
type User record {|
    int id;
    string name;
    boolean isMember;
|};

2. Include the documentation along with the record field.

# Represents a user.
type User record {|
    # Id of the user
    int id;
    # Name of the user
    string name;
    # Whether the user is a member
    boolean isMember;
|};

The latter approach is used as a best practice within the Ballerina team. Even with the considered approach, it is yet unclear whether to leave a space between the fields for better readability. IMO, when a node has more metadata, having a space in between can enhance the readability of the code.

// Approach 1: Without the spaces in between
# Represents a user.
type User1 record {|
    # Id of the user
    @constraint:Int {
        maxDigits: 10
    }
    int id;
    # Name of the user
    @constraint:String {
        minLength: 5,
        maxLength: 20
    }
    string name;
    # Address of the user
    @constraint:String {
        minLength: 20,
        maxLength: 100
    }
    string address;
|};


// Approach 2: With the spaces in between
# Represents a user.
type User2 record {|
    # Id of the user
    @constraint:Int {
        maxDigits: 10
    }
    int id;

    # Name of the user
    @constraint:String {
        minLength: 5,
        maxLength: 20
    }
    string name;

    # Address of the user
    @constraint:String {
        minLength: 20,
        maxLength: 100
    }
    string address;
|};