Skip to content

jsdoc comments are placed after property name #545

Open
@henhal

Description

@henhal

Is it intentional that comments for properties using another (non-primitive) schema look like this?

            resourceId: /**
             * Resource ID
             * example:
             * 6e781f03-668c-420c-82c0-06853620dc3b
             */
            ResourceId /* uuid */;

instead of like this:

            /**
             * Resource ID
             * example:
             * 6e781f03-668c-420c-82c0-06853620dc3b
             */
            resourceId: ResourceId /* uuid */;

I'm not sure I understand why. It's normal jsdoc practice to comment before properties, not between properties and their type.
I understand that this may be opinionated, but for me this looks cluttered and confusing.

(Also, the fact that the uuid part (from format: uuid) comes after the type adds to the confusion even further.)

Schema:

      "ResourceId": {
        "type": "string",
        "description": "Resource ID",
        "format": "uuid",
        "example": "6e781f03-668c-420c-82c0-06853620dc3b"
      },
      "Foo": {
        "type": "object",
        "properties": {
          "resourceId": {
            "$ref": "#/ResourceId"
          }
        }
      }

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions