Check IterCallableYieldTypesMatchDoc

iter-callable-yield-types-match-doc - Iter callable yield types match doc

Explanation

Verifies that the @loop type annotations in an iter callable's documentation match its reasoned _loopbody yield types. Issues are raised in the following situations:

• A @loop annotation is missing on an iter callable that yields values.
• A @loop annotation is present on a non-iter callable.
• A @loop type does not match the reasoned yield type.
• A @loop annotation carries no type at all.

Yield slots whose type is unknown (e.g. from an unresolved method call) are skipped for mismatch reporting; those are covered by UndefinedMethodCallResultTypedCheck.

Examples

Type mismatch

_iter _method example_exemplar.example_method()
    ## @loop {float}
    _loopbody(1)
_endmethod

Raises an issue because the callable is documented to yield float but actually yields integer.

Missing @loop

_iter _method example_exemplar.example_method()
    _loopbody(1)
_endmethod

Raises an issue because the iter callable yields a value but has no @loop annotation.

@loop on non-iter callable

_method example_exemplar.example_method()
    ## @loop {integer}
_endmethod

Raises an issue because @loop is only valid on iter callables.

@loop without a type

_iter _method example_exemplar.example_method()
    ## @loop {integer} the value, which
    ## @loop must be yielded one at a time
    _loopbody(1)
_endmethod

Raises an issue because the type in a @loop annotation is optional in the grammar: the wrapped description line parses as a second, untyped @loop declaration. Untyped annotations are discarded before any type comparison, so without this check the mistake goes unnoticed while the callable is recorded as yielding two values.

Note

This page is generated. Any changes made to this page through the wiki will be lost in the future.