Page MenuHomePhabricator

Do not warn about missing function doc comment when parameter and return types are fully specified by type hints
Open, LowPublic

Description

This is allowed:

/**
 * @param Bar $bar
 * @param Baz $baz
 * @return Foo
 */
public function getFoo( Bar $bar, Baz $baz ): Foo {}

This throws MediaWiki.Commenting.FunctionComment.MissingDocumentationPublic:

public function getFoo( Bar $bar, Baz $baz ): Foo {}

but the only difference is that the first one is harder to read and wastes more space.

Either we should require human-readable description for methods / parameters, or not require the doc block at all when the types are already fully specified.

Event Timeline

Some thoughts:

  • array types should still have documentation for what it is an array of
  • unless all parameters and the return are documented with strong typehints, the sniff should still be run, since we shouldn't have only some parameters documented in the doc block
  • if there is no return typehint, check whether anything other that an empty return is ever used - if not, it isn't needed (though void would be allowed) so that shouldn't trigger the sniff

array types should still have documentation for what it is an array of

We accept @param array so I don't think it makes sense to reject array typehints. (In the longer term, maybe we should reject both and require explicit array typing.)

unless all parameters and the return are documented with strong typehints, the sniff should still be run, since we shouldn't have only some parameters documented in the doc block

Do you mean something specific with *strong* typehint? AFAIK PHP has only one kind of typehint. Otherwise, agreed.

if there is no return typehint, check whether anything other that an empty return is ever used - if not, it isn't needed (though void would be allowed) so that shouldn't trigger the sniff

I would keep it simple and require either a void typehint or a doc block.

array types should still have documentation for what it is an array of

unless all parameters and the return are documented with strong typehints, the sniff should still be run, since we shouldn't have only some parameters documented in the doc block

Do you mean something specific with *strong* typehint? AFAIK PHP has only one kind of typehint. Otherwise, agreed.

I use "strong typehint" to refer to the typehints within the php code, separate from typehints in the doc blocks

if there is no return typehint, check whether anything other that an empty return is ever used - if not, it isn't needed (though void would be allowed) so that shouldn't trigger the sniff

I would keep it simple and require either a void typehint or a doc block.

That works too