Proposal: Emit warning on public functions without a proper function signature

[eksperimental]

Hi all,
Since documentation is taken seriously in Elixir,
I would like to propose to emit a warning when a public function
does not a have a proper/complete function signature.
I describe an improper fucntion signature would look like this in your
IEx/ExDoc documenation:

your_function_name(arg1, arg2, options)

This is do to the fact of not using argument names in your function
definitions, for example:

def your_function_name(10, 20, options) when is_list(options),
do: ...

As of now, IEx and ExDoc do a good job as guessing these signatures,
based on the function argument names of the various function clauses
when they are not explicitely declared,
but I would like Elixir to emit a warning when it will end up looking
like `argX`.

We could introduce this feature as a flag:
--warn-on-imcomplete-signature

And eventually make it by default.

As of now, in order to avoid this, I need to execute: `mix docs` and
then grep the doc/ folder looking for `argX` with a ·

This feature will integrate well with `--warnings-as-errors` and CI to
help to maintain up a high standard in the documentation of our
libraries.

Looking forward to hearing your opinion,
- Eksperimetnal

[José Valim]

While I can see this being useful for libraries, I think it is a very strong imposition for applications and I don’t think it should be the job of the compiler to enforce it.

So my suggestion is to implement this as linter/credo check.

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/61bf2760.1c69fb81.edfdb.56f2SMTPIN_ADDED_MISSING%40gmr-mx.google.com.

[Kurtis Rainbolt-Greene]

To piggy back off this, perhaps it's prudent to scope some warnings to (somehow) when a your code is compiling vs the imported code? First because of what José describes here, and second it also means my students won't get so sidetracked when they see a ton of warnings from their libraries.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4JZeKcVFN9%3Dqty%2BJ%2B23z82GTw7qiWrZfauvcCULthO70A%40mail.gmail.com.

--

Kurtis Rainbolt-Greene,

Software Developer & Founder of Difference Engineers

202-643-2263

[eksperimental]

That is why the initial proposal was to emit the warning only when the
flag was explicetely passed.

> > https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4JZeKcVFN9%3Dqty%2BJ%2B23z82GTw7qiWrZfauvcCULthO70A%40mail.gmail.com
> > <https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4JZeKcVFN9%3Dqty%2BJ%2B23z82GTw7qiWrZfauvcCULthO70A%40mail.gmail.com?utm_medium=email&utm_source=footer>
> > .
> >
>
>

[José Valim]

Elixir does not have optional warnings. Or the warnings are always useful and they are always enabled. Or they are not always useful and therefore it should not be the responsibility of the compiler to enforce it.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/61c085ae.1c69fb81.53233.5606SMTPIN_ADDED_MISSING%40gmr-mx.google.com.

[eksperimental]

Good point, and that pretty much explains why this flag is a non-viable
feature.

I will make a proposal to Credo.
Thank you guys for your input.