Skip to content

documentation-required

Full name
@azure-tools/typespec-azure-core/documentation-required

Enums, models, operations, and their members/properties should have documentation. Use doc comments (/** */) to provide descriptions.

❌ Incorrect

Section titled “❌ Incorrect”

Model without documentation:

model Pet {
  name: string;
}

Operation without documentation:

op read(): void;

Enum without documentation:

enum PetKind {
  Cat,
  Dog,
}

✅ Correct

Section titled “✅ Correct”
/** A pet in the system. */
model Pet {
  /** The name of the pet. */
  name: string;
}


/** Reads a pet resource. */
op read(): Pet;


/** The kind of pet. */
enum PetKind {
  /** A cat. */
  Cat,


  /** A dog. */
  Dog,
}