Re: [elpa] master a79dd37 07/11: fsm: Fix checkdoc errors

Re: [elpa] master a79dd37 07/11: fsm: Fix checkdoc errors

[Stefan Monnier]

> -  "Send EVENT to FSM asynchronously.
> +  "Send FSM EVENT asynchronously.

Hmm... was that because checkdoc asked you to put the args in the order
of appearance?
I think this part of checkdoc's recommendations is not to be taken
too seriously.
It's OK to follow this principle for things like

   Arg FOO does toto.
   Arg BAR does titi.

But clarity of the text takes precedence.


        Stefan

Re: [elpa] master a79dd37 07/11: fsm: Fix checkdoc errors

[Thomas Fitzsimmons]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> -  "Send EVENT to FSM asynchronously.
>> +  "Send FSM EVENT asynchronously.
>
> Hmm... was that because checkdoc asked you to put the args in the order
> of appearance?

Yes, I was trying to make fsm.el "checkdoc-clean".

> I think this part of checkdoc's recommendations is not to be taken
> too seriously.
> It's OK to follow this principle for things like
>
>    Arg FOO does toto.
>    Arg BAR does titi.
>
> But clarity of the text takes precedence.

OK, I reverted these parts, including the last one where I liked the
previous wording better.

Thomas

Re: [elpa] master a79dd37 07/11: fsm: Fix checkdoc errors

[Stefan Monnier]

> Yes, I was trying to make fsm.el "checkdoc-clean".

I think this is indeed desirable in theory, but Someone™ should first
tweak checkdoc to remove some of the more debatable recommendations (at
least in its default state).  IIRC another example is the recommendation
to name boolean vars with a "-flag" suffix (which I think is a poor
idea).


        Stefan