[PATCH docs] Take a stab at a proper DBUS API document.

[Brad Bishop]

Thx Jeremy

> On May 12, 2016, at 4:56 AM, Jeremy Kerr <jk at ozlabs.org> wrote:
> 
> Hi Brad,
> 
> This is awesome, thanks for taking the time and writing up the proper
> content here.
> 
> Since your change will establish a few conventions around how the
> interfaces will be properly documented, I'm being extra-nitpicky about
> this, so have a few changes listed below. If you'd prefer, I can do this
> reformatting myself, but we should still address this somehow, before
> merging.
> 
> 
>> +# OpenBMC DBUS API
> 
> Most of the other docs use the ====/---- style of for level 1 & level 2
> headers, as it makes the text version of the markdown look more like a
> header.

done!

> 
>> +The Phosphor distibution provides sample applications that implement off all the interfaces and objects listed below.  Alternative or more feature complete applications are possible by implementing parts of this DBUS API.
> 
> Can we wrap at 80 columns, where it makes sense? Things that *need* to
> be wider are fine, but this makes things readable for folks who use
> 80-cols by default.

done!

> 
>> +| name         | in signature | out signature | description                              |
>> +| ------------ | ------------ | ------------- | ---------------------------------------- |
>> +| sendMessage  | yyyyyay      | x             | Send an IPMI message to the host processor firmware. |
> 
> Should we backtick-escape these names (and paths)? It'll also avoid any
> issues with inline < and > characters (which Chris picked up in his
> review).

done!

> 
> Looks like this table format is also compatible with the pandoc markdown
> implementation, which is great news if/when we want to create a PDF
> document including this.
> 
> Speaking of which, pandoc also supports a few different methods of doing
> tables, some of which allow us to break long lines (which may make the
> text-format of the doc easier to read):
> 
>  http://pandoc.org/README.html#tables
> 

Yes, tables in github are ugly.  I tried the other formats and github doesn’t render any of them.

I cleaned them up best I could.  If in the future someone wants to restructure it without tables it won’t bother me any.


> However, if we do end up using one of these, we'll need to check that it
> still renders correctly in github.
> 
> Cheers,
> 
> 
> Jeremy
> _______________________________________________
> openbmc mailing list
> openbmc at lists.ozlabs.org
> https://lists.ozlabs.org/listinfo/openbmc