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

[Jeremy Kerr <jk@ozlabs.org>]

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.

> +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.

> +| 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).

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

However, if we do end up using one of these, we'll need to check that it
still renders correctly in github.

Cheers,


Jeremy