Recommended doc-comment approach for records

[vernal wraith]

We can use both of the below approaches to add doc-comments to a Ballerina record.

Which is the recommended?

approach 1

# Provides extracted tools and service URL from the OpenAPI specification.
#
# + serviceUrl - Extracted service URL from the OpenAPI specification if there is any
# + tools - Extracted Http tools from the OpenAPI specification
public type HttpApiSpecification record {|
    string serviceUrl?;
    HttpTool[] tools;
|};

approach 2

# Provides extracted tools and service URL from the OpenAPI 
public type HttpApiSpecification record {|
    # Extracted service URL from the OpenAPI specification if there is any
    string serviceUrl?;
    # Extracted Http tools from the OpenAPI 
    HttpTool[] tools;
|};

[analog fox]

Approach 2 is what is recommended. Approach 1 is what we had before approach 2 was introduced.

[sharp tree]

You can find more details on here.

https://ballerina.io/learn/generate-code-documentation/#write-ballerina-documentation

[vernal wraith]

got it, thank you @analog fox !

[wide ember]

@analog fox Isn't it better add a section or sample to the above learn page specifically about records?