Doc comment application of @param doc

[timotheeguerin]

With the introduction of doc comment setting the doc of types there is some cases that are not covered yet as well as some consistency we'd have to choose.

Playground Link

Right now there is the following problems:

• the behavior doesn't work for op is
• does not work on model is dev doc comments does not consistently set @doc for Azure libs #1994
• doc comment are overriden by @doc but in @param case feels like it should be the other way often(when using op is, ...spread)

[timotheeguerin]

For the op is and model is case we could estabilish this logic:

• doc comment will apply @doc on a node it it isn't explicilty set on the node itself so it won't care if it was set in the sourceOperation or sourceModel

[timotheeguerin]

This can be discussed in 2 problems:

1. Doc comment doesn't override doc of parent on model is or op is

Playground showing the different cases

Problem is the current implementation will inject a decorator as the "first" decorator to run on a type if there is doc comment on the node. This means that if you have model is and the base type has its own doc comment or @doc decorator those will run after and then override the value specified on the target type.
The advantage of this logic was that it is shared for all types in the compiler there is no special case.

Proposal for this issue:

For certain types we should inject the doc comment at a different point in the checking. For model and operation the order of operation should be:

• start creating the type
• resolve model is/op is if any
• copy over the properties(including the decorators)
• Inject the doc comment as a @doc decorator if present
• Resolve the decorators of the type
• Finish the type

2. @param doesn't apply when using spread or op is

Playground

This case is a little more tricky. The current logic is when checking a ModelProperty it will check if that model property is inside an operation as a parameter and then apply the doc comment decorator.

To make this work we need to be adding the doc comment when checking the operation. However we also need to make sure a doc comment doesn't override an explicit @doc

[timotheeguerin]

Scenario 1:

Change: move logic to checkDecorators instead of finishType should just solve all those problems

/** Doc comment */
@doc("@doc1")
model Foo {} // win: @doc1

/** Doc comment */
model FooWithAugment {} // win: @doc1
@@doc(FooWithAugment, "@doc1");

/** Override */
model IsBase is Foo; // win: Override

[timotheeguerin]

Proposal for @param

Problem

Playground

This case is a little more tricky. The current logic is when checking a ModelProperty it will check if that model property is inside an operation as a parameter and then apply the doc comment decorator.

Requirements

• You can use @param to describe a parameter in the operation if it is defined explicilty or via op is or spread from a model
• You should still be able to augment the paraemters after and that should win over the @param dev doc
• Specifying @doc on the property and @param need to make sense on who wins.

Proposal

Each operation parameters is a model that is unique with properties that are unique object and can be augmented independently(when properties are spread or op is properties are linked with sourceProperty)

op base(one: string): void;

op child is base;

@@doc(child::parameters.one, "Only set doc for child one param");

This means that we can think of using @param like augmenting the parameters of the operation the @param is used on.

Logic would be as follow: (✅ means we are already doing that, ➡️ are new steps)

• ✅ Start checking operation
• ➡️ For each @param found register the decorator on the operation parameter symbol(as an augment decorator)
• ✅ Check if op is and resolve source operation
• ✅ Check parameters
  • ✅ resolve any spread model
  • ✅ finish each property
    • ✅ resolve augment decorators for the property. This means it would now include the value included by @param
• ✅ finish creating operation

With this logic it would mean the following

/**
 * @param one Doc comment
 */
op base(one: string): void;
// getDoc(base.one) === "Doc Comment"

/**
 * @param one Doc comment
 */
op base(@doc("Explicit") one: string): void;
// getDoc(base.one) === "Explicit"

/**
 * @param one Doc comment
 */
op base(one: string): void;

@@doc(base::parameters.one, "Override");
// getDoc(base.one) === "Override"

/**
 * @param one Doc comment
 */
op base(one: string): void;

op child is base;

// getDoc(child.one) === "Doc Comment"

/**
 * @param one Doc comment
 */
op base(one: string): void;


/**
 * @param one Override for child
 */
op child is base;

// getDoc(child.one) === "Override for child"

/**
 * @param one Doc comment
 */
op base(one: string): void;


/**
 * @param one Override for child
 */
op child is base;

@@doc(child::parameters.one, "Override for child again")
// getDoc(child.one) === "Override for child again"

model A {
  @doc("Via model") one: string
}
op base(...A): void;

// getDoc(base.one) === "Via model"

model A {
  @doc("Via model") one: string
}
/**
 * @param one Doc comment
 */
op base(...A): void;

// getDoc(base.one) === "Doc Comment"

[timotheeguerin]

Implementation issue #2233