Re: [PATCH v4 01/10] battery: Add generic device battery documentation

Johan,
On 09/28/2012 12:59 PM, Johan Hedberg wrote:

Hi Chen,

On Mon, Sep 24, 2012, chen.ganir@ti.com wrote:

quoted

+BlueZ D-Bus Battery API description
+****************************************

Please keep the "underline" consistent with the length of the text above
it.

quoted

+	Texas Instruments, Inc. [off-list ref]

What's this supposed to be? If you want a copyright statement here then
make it of the proper format. Author info is not needed as we have the
AUTHORS file and the commit history.

Would you please specify what is the proper copyright message format ? 
doc/adapter-api.txt, doc/health-api.txt have two different styles. 
doc/oob-api.txt has a third style (AUTHOR <author@email> for COMPANY),
doc/media-api.txt for example does not have any copyright information. 
In addition - you say author information is not required, yet all other 
copyright messages contain this. Is this a new policy ? If so, please 
specify the proper copyright message.

quoted

+Device Battery hierarchy
+=====================================

Same thing with the consistency of the "underline"

Ok.

quoted

+Service		org.bluez
+Interface	org.bluez.Battery
+Object path	[variable prefix]/{hci0,..}/dev_XX_XX_XX_XX_XX_XX/BATTYYYY
+YYYY is numeric value between 0 and 9999.

I don't think you need a separate comment for the "YYY". We don't have
that for the "XX" stuff either.

Ok.

quoted

+		array{object} Batteries [readonly]

I guess you should mark this with [experimental] since it'll be removed
with the advent of ObjectManager.

What is the difference between the Batteries property and the services 
or UUIDs property in device-api.txt ? Should all of them get marked with 
experimental ?

Johan

-- 
BR,
Chen Ganir
Texas Instruments