DocComments should support "@prop <propName>" inside comments on model elements to make documenting a model a single block comment

[garethj-msft]

Graph API reviewers prefer the following syntax for authoring and reviewing to provide greater visual scanning on read (at the cost of editing in two places for updates).

/**
 * This object represents what actions are allowed on a task, such as move or delete.
 * It derives from `plannerPropertyRule`.
 * All values that are null use the value of the parent entity's `defaultRule` field.
 * @prop move Where can the task be moved valid values are `allow`, `moveBetweenBuckets`, `moveBetweenPlans`, and `block`.
 * @prop title Valid values are `block` or `allow`. `block` indicates edits are blocked `allow` indicates there are no restrictions.   
 * @prop notes Valid values are `block` or `allow`. `block` indicates edits are blocked `allow` indicates there are no restrictions.
 * @prop references Valid values are `add`, `delete`, `update`, `block`, and `allow`.   
 */
@complex model plannerTaskPropertyRule {
  @workloadName("Move") move: string[];
  @workloadName("Title") title: string[];
  @workloadName("Notes") notes: string[];
  @workloadName("References") references: plannerFieldRules;
}

This would be semantically equivalent to:

/**
 * This object represents what actions are allowed on a task, such as move or delete.
 * It derives from `plannerPropertyRule`.
 * All values that are null use the value of the parent entity's `defaultRule` field.
 */
@complex model plannerTaskPropertyRule {
  /** Where can the task be moved valid values are `allow`, `moveBetweenBuckets`, `moveBetweenPlans`, and `block`. */
  @workloadName("Move") move: string[];

  /** Valid values are `block` or `allow`. `block` indicates edits are blocked `allow` indicates there are no restrictions. */
  @workloadName("Title") title: string[];

  /** Valid values are `block` or `allow`. `block` indicates edits are blocked `allow` indicates there are no restrictions. */
  @workloadName("Notes") notes: string[];

  /** Valid values are `add`, `delete`, `update`, `block`, and `allow`. */  
  @workloadName("References") references: plannerFieldRules;
}

Similarly for enums, @member <membername> embeddings should be supported for consistency of commenting style across structured elements.

[timotheeguerin]

All those questions are probably going to get resolved tomorrow during the design meeting for @param #1946 and we most likely have the same logic here too

But need to make sure we have a consistent logic for the following:

model A {
  /** Doc comment */
  a: string
}

/** 
 * @prop a override a doc for b
*/
model B {
  ...A
}

I would expect B.a to have override a doc for b as doc

model A {
  /** Doc comment */
  a: string
}

/** 
 * @prop a override a doc for b
*/
model B {
  ...A
}

@@doc(B.a, "Override again")

I would expect B.a to have Override again as doc

[markcowl]

Related to #2233

[garethj-msft]

Yay - great to see this moving - we've really sold it to teams for Graph.

[garethj-msft]

@mario-guerra any chance we can get this prioritized? We're trying hard to sell TypeSpec as master to our docs team and everyone really wants this.

[mario-guerra]

Pinging @allenjzhang for comment on prioritization.

[timotheeguerin]

Pr fixing the issue with @param is here #3517 this means the same logic should be able to be reused for @prop

[timotheeguerin]

model Base {
  /** Doc comment on prop */
  prop: string;
}
// getDoc(Base.prop) === "Doc comment on prop"

model Base {
  /** Doc comment on prop */
  @doc("Explicit")
  prop: string;
}
// getDoc(Base.prop) === "Explicit"

/**
 * @prop prop Doc comment from model
 */
model Base {
  prop: string;
}
// getDoc(Base.prop) === "Doc comment from model"

/**
 * @prop prop Doc comment from model
 */
model Base {
  /** Doc comment on prop */
  prop: string;
}
// getDoc(Base.prop) === "Doc comment on prop"

model Base {
  /** Doc comment on prop */
  prop: string;
}

/**
 * @prop prop Doc comment from model override
 */
model Child {
  ...Base
}
// getDoc(Child.prop) === "Doc comment from model override"

model Base {
  /** Doc comment on prop */
  prop: string;
}

/**
 * @prop prop Doc comment from model override
 */
model Child {
  ...Base
}
@@doc(Child.prop, "override via augment")
// getDoc(Child.prop) === "override via augment"

[timotheeguerin]

PR #3527