Documentation generation currently broken for arrays of objects

[iann0036]

Generated documentation is currently generating as:

"<a href="#arrayofobj" title="ArrayOfObj">ArrayOfObj</a>" : <i>[ [ <a href="arrayofobj.md">ArrayOfObj</a>, ... ], ... ]</i>,

i.e. it is doubly encapsulating. Additionally, the object properties file (arrayofobj.md in the above example) is not currently being generated.

[ammokhov]

@iann0036 could you please provide schema that you are working off

[iann0036]

Hey @ammokhov,

It looks like this becomes an issue only for objects that are not $ref'd. Using the example schema, but replacing the $ref'd Tag definition with a copy of it does this, as per the below example:

{
    "typeName": "Example::Example::Resource",
    "description": "An example resource schema demonstrating some basic constructs and validation rules.",
    "sourceUrl": "https://github.com/aws-cloudformation/aws-cloudformation-rpdk.git",
    "definitions": {
        "InitechDateFormat": {
            "$comment": "Use the `definitions` block to provide shared resource property schemas",
            "type": "string",
            "format": "date-time"
        },
        "Memo": {
            "type": "object",
            "properties": {
                "Heading": {
                    "type": "string"
                },
                "Body": {
                    "type": "string"
                }
            },
            "additionalProperties": false
        },
        "Tag": {
            "description": "A key-value pair to associate with a resource.",
            "type": "object",
            "properties": {
                "Key": {
                    "type": "string",
                    "description": "The key name of the tag. You can specify a value that is 1 to 128 Unicode characters in length and cannot be prefixed with aws:. You can use any of the following characters: the set of Unicode letters, digits, whitespace, _, ., /, =, +, and -.",
                    "minLength": 1,
                    "maxLength": 128
                },
                "Value": {
                    "type": "string",
                    "description": "The value for the tag. You can specify a value that is 0 to 256 Unicode characters in length and cannot be prefixed with aws:. You can use any of the following characters: the set of Unicode letters, digits, whitespace, _, ., /, =, +, and -.",
                    "minLength": 0,
                    "maxLength": 256
                }
            },
            "required": [
                "Key",
                "Value"
            ],
            "additionalProperties": false
        }
    },
    "properties": {
        "TPSCode": {
            "description": "A TPS Code is automatically generated on creation and assigned as the unique identifier.",
            "type": "string",
            "pattern": "^[A-Z]{3,5}[0-9]{8}-[0-9]{4}$"
        },
        "Title": {
            "description": "The title of the TPS report is a mandatory element.",
            "type": "string",
            "minLength": 20,
            "maxLength": 250
        },
        "CoverSheetIncluded": {
            "description": "Required for all TPS Reports submitted after 2/19/1999",
            "type": "boolean"
        },
        "DueDate": {
            "$ref": "#/definitions/InitechDateFormat"
        },
        "ApprovalDate": {
            "$ref": "#/definitions/InitechDateFormat"
        },
        "Memo": {
            "$ref": "#/definitions/Memo"
        },
        "SecondCopyOfMemo": {
            "description": "In case you didn't get the first one.",
            "$ref": "#/definitions/Memo"
        },
        "TestCode": {
            "type": "string",
            "enum": [
                "NOT_STARTED",
                "CANCELLED"
            ]
        },
        "Authors": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "Tags": {
            "description": "An array of key-value pairs to apply to this resource.",
            "type": "array",
            "uniqueItems": true,
            "insertionOrder": false,
            "items": {
                "description": "A key-value pair to associate with a resource.",
                "type": "object",
                "properties": {
                    "Key": {
                        "type": "string",
                        "description": "The key name of the tag. You can specify a value that is 1 to 128 Unicode characters in length and cannot be prefixed with aws:. You can use any of the following characters: the set of Unicode letters, digits, whitespace, _, ., /, =, +, and -.",
                        "minLength": 1,
                        "maxLength": 128
                    },
                    "Value": {
                        "type": "string",
                        "description": "The value for the tag. You can specify a value that is 0 to 256 Unicode characters in length and cannot be prefixed with aws:. You can use any of the following characters: the set of Unicode letters, digits, whitespace, _, ., /, =, +, and -.",
                        "minLength": 0,
                        "maxLength": 256
                    }
                },
                "required": [
                    "Key",
                    "Value"
                ],
                "additionalProperties": false
            }
        }
    },
    "additionalProperties": false,
    "required": [
        "TestCode",
        "Title"
    ],
    "readOnlyProperties": [
        "/properties/TPSCode"
    ],
    "primaryIdentifier": [
        "/properties/TPSCode"
    ],
    "handlers": {
        "create": {
            "permissions": [
                "initech:CreateReport"
            ]
        },
        "read": {
            "permissions": [
                "initech:DescribeReport"
            ]
        },
        "update": {
            "permissions": [
                "initech:UpdateReport"
            ]
        },
        "delete": {
            "permissions": [
                "initech:DeleteReport"
            ]
        },
        "list": {
            "permissions": [
                "initech:ListReports"
            ]
        }
    }
}

This may also be related to the still outstanding https://github.com/aws-cloudformation/cloudformation-cli/issues/406

[iann0036]

This actually could just be when the definition name and property name match 🤔