Subject: Re: [PATCH] ASoC: fsl_sai: Add asynchronous mode support

From: Nicolin Chen <[email-masked]>
Date: Wed, 6 Aug 2014 10:42:37 +0800

Hi Varka,

On Tue, Aug 05, 2014 at 04:44:29PM +0530, Varka Bhadram wrote:
> On 08/05/2014 04:37 PM, Nicolin Chen wrote:
> >Hi Varka,
> >
> >On Tue, Aug 05, 2014 at 04:29:50PM +0530, Varka Bhadram wrote:
> >>>diff --git a/Documentation/devicetree/bindings/sound/fsl-sai.txt b/Documentation/devicetree/bindings/sound/fsl-sai.txt
> >>>index 0f4e238..77864f4 100644
> >>>--- a/Documentation/devicetree/bindings/sound/fsl-sai.txt
> >>>+++ b/Documentation/devicetree/bindings/sound/fsl-sai.txt
> >>>@@ -24,6 +24,22 @@ Required properties:
> >>>  - big-endian-data: If this property is absent, the little endian mode will
> >>>    be in use as default, or the big endian mode will be in use for all the
> >>>    fifo data.
> >>>+- fsl,sai-synchronous-rx: This is a boolean property. If present, indicating
> >>>+  that SAI will work in the synchronous mode (sync Tx with Rx) which means
> >>>+  both the transimitter and receiver will send and receive data by following
> >>>+  receiver's bit clocks and frame sync clocks.
> >>>+- fsl,sai-asynchronous: This is a boolean property. If present, indicating
> >>>+  that SAI will work in the asynchronous mode, which means both transimitter
> >>>+  and receiver will send and receive data by following their own bit clocks
> >>>+  and frame sync clocks separately.
> >>>
> >>Would be readable if it like this...
> >>
> >>fsl,sai-synchronous-rx: This is a boolean property. If present, indicating
> >>			that SAI will work in the synchronous mode (sync Tx with Rx) which means
> >>			both the transimitter and receiver will send and receive data by following
> >>			receiver's bit clocks and frame sync clocks.
> >>- fsl,sai-asynchronous: This is a boolean property. If present, indicating
> >>			that SAI will work in the asynchronous mode, which means both transimitter
> >>			and receiver will send and receive data by following their own bit clocks
> >>			and frame sync clocks separately.
> >I agree, however, the doc was initialized in that format. Adding
> >indentations for these two appended lines makes the whole text
> >look weird. :(
> 
> Reading comfortably is important for us...  :-)
> see this:http://lxr.free-electrons.com/source/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt#L46

I know how to write a binding doc with indentations to make it clear.

What I'm talking about is that the doc was created without indentations,
so I don't feel comfortable to add indentations starting from this patch
while leaving the old lines in totally a different style because It's not
helpful to make people read comfortably at all but only forcing people to
think why these two lines are so special to take some steps back here.

So personally I agree with your idea to make doc more readable. But what
I prefer to do is not having a conversation on the style within this patch
but to create an extra style-refinement patch later after this one.

Let's just focus on the function itself right now. We can later send a
patch to refine this entire doc. Won't you think it's a better idea? :)

Thank you
Nicolin