Infer function types when no `@param` or `@return` tags are present #157

YetAnotherClown · 2024-10-16T23:38:43Z

Allow the use of @function and @method to explicitly tell Moonwave whether an inferred function is a method or not by inferring types when no @param or @return tags are present within the doc comment.

Why

Currently, the way users tell Moonwave whether to infer the types of a function is by omitting the @function and @method tags. By doing this, users are left unable to explicitly state the name of their doc entry and whether it is a method or not. Sometimes, users do want the ability to do both of these things while still inferring the types of their functions.

Considerations

FunctionDeclarations with a Method Colon

In this case, it should infer the types, but it should not ignore the first parameter.

--- @method bar
--- @within foo
function foo:bar(a: number, b: string)

end

Moonwave should keep all parameters when parsing a FunctionDeclaration with a method colon.

Parameter/Return Tags with Empty Types

@parameter and @return tags should be ignored if their type field is empty. This is to retain the current behavior as seen below.

--- @within foo
--- @param a -- This is a comment
--- @param b -- This is another comment
function foo:bar(a: number, b: string)

end

Use Case Examples

Inlined Functions

A common pattern to inline functions makes it difficult to get desirable results from Moonwave doc comments.

Consider this use case from Jecs here, modified to have a Moonwave doc comment.

--- @within world
local function world_entity(world: World): i53
	local entityId = (world.nextEntityId :: number) + 1
	world.nextEntityId = entityId
	return entity_index_new_id(world.entityIndex, entityId + EcsRest)
end

Here is what we want:

This to be parsed as a method by Moonwave
The method name to be entity
Parameter and return types to be inferred, but ignore the first parameter

Currently, we're unable to get any three of these results with this pattern. We can fix all three with this change, by explicitly stating it is a method and explicitly stating the name in a @method. Moonwave will also know to ignore the first parameter if types are being inferred from a FunctionDeclarations with a method colon, e.g. function foo:bar().

Methods Within Type Definitions

While not supported by Moonwave, this could be worthwhile syntax to support in Moonwave and we should consider future possibilities.

type Foo = {
	--- @method bar
	--- @within foo
	bar: (self: Foo, a: number, b: string) -> ()
}

If Moonwave would be to support this syntax, without the --- @method bar with the changes proposed in this issue, it would not be obvious that this is meant to be a method. In this case, we can explicitly tell Moonwave we want this to be a method and to ignore self: Foo.

The text was updated successfully, but these errors were encountered:

YetAnotherClown added enhancement New feature or request extractor labels Oct 16, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Infer function types when no `@param` or `@return` tags are present #157

Infer function types when no `@param` or `@return` tags are present #157

Infer function types when no @param or @return tags are present #157

Infer function types when no @param or @return tags are present #157

Comments

Why

Considerations

FunctionDeclarations with a Method Colon

Parameter/Return Tags with Empty Types

Use Case Examples

Inlined Functions

Methods Within Type Definitions

Infer function types when no `@param` or `@return` tags are present #157

Infer function types when no `@param` or `@return` tags are present #157