What is the best API documentation approach for Ballerina record types?

Question

Which one is the recommended documentation approach for Ballerina record types, considering the below options?

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;
|};

Answer 1

Approach 2 is what is recommended.

You can find more details on here. https://ballerina.io/learn/generate-code-documentation/#write-ballerina-documentation