Re: [PATCH v2 1/2] ASoC: fsl_mqs: Don't check clock is NULL before calling clk API

In-Reply-To: [off-list ref]

I guess that it should be sufficient to specify such a field once
for the header information.

Because clk_prepare_enable and clk_disable_unprepare should
check input clock parameter is NULL or not internally,

I find this change description unclear.

then we don't need to check them before calling the function.

Please use an imperative wording for the commit message.
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/submitting-patches.rst?id=dd0d718152e4c65b173070d48ea9dfc06894c3e5#n151

Regards,
Markus

On Tue, Jun 23, 2020 at 3:38 PM Markus Elfring [off-list ref] wrote:

quoted

In-Reply-To: [off-list ref]

I guess that it should be sufficient to specify such a field once
for the header information.

seems it's caused by my "git format-patch" command, I will update
it, hope it is better next time.

quoted

Because clk_prepare_enable and clk_disable_unprepare should
check input clock parameter is NULL or not internally,

I find this change description unclear.

    clk_prepare_enable and clk_disable_unprepare check the input
    clock parameter in the beginning of the function, if the parameter
    is NULL, clk_prepare_enable and clk_disable_unprepare will
    return immediately.

    So Don't need to check input clock parameters before calling clk
    API.

Do you think this commit message is better?

best regards
wang shengjiu

    clk_prepare_enable and clk_disable_unprepare check the input
    clock parameter in the beginning of the function,

These functions call further functions which perform null pointer checks.

                                                      if the parameter
    is NULL, clk_prepare_enable and clk_disable_unprepare will
    return immediately.

The interpretation of these function implementations seems to be reasonable.
Would you like to achieve any improvements for the corresponding software documentation?

    So Don't need to check input clock parameters before calling clk API.

What do you find imperative in this wording?

Another wording alternative:
   Thus omit extra null pointer checks before four function calls.

Regards,
Markus

On Tue, Jun 23, 2020 at 4:55 PM Markus Elfring [off-list ref] wrote:

quoted

    clk_prepare_enable and clk_disable_unprepare check the input
    clock parameter in the beginning of the function,

These functions call further functions which perform null pointer checks.

quoted

                                                      if the parameter
    is NULL, clk_prepare_enable and clk_disable_unprepare will
    return immediately.

The interpretation of these function implementations seems to be reasonable.
Would you like to achieve any improvements for the corresponding software documentation?

Which document do you mean?

quoted

    So Don't need to check input clock parameters before calling clk API.

What do you find imperative in this wording?

Another wording alternative:
   Thus omit extra null pointer checks before four function calls.

Regards,
Markus

quoted

quoted

                                                      if the parameter
    is NULL, clk_prepare_enable and clk_disable_unprepare will
    return immediately.

The interpretation of these function implementations seems to be reasonable.
Would you like to achieve any improvements for the corresponding software documentation?

Which document do you mean?

Example:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/linux/clk.h?id=dd0d718152e4c65b173070d48ea9dfc06894c3e5#n905
https://elixir.bootlin.com/linux/v5.7.2/source/include/linux/clk.h#L905

Regards,
Markus