doc: format with markdownlint
Signed-off-by: Patrick Williams <patrick@stwcx.xyz>
Change-Id: I53c76c240a893ede5314839e70fe82b93325d59a
diff --git a/.markdownlint.yaml b/.markdownlint.yaml
new file mode 100644
index 0000000..b6f0e5a
--- /dev/null
+++ b/.markdownlint.yaml
@@ -0,0 +1 @@
+default: true
diff --git a/README.md b/README.md
index 8a462d7..64e5984 100644
--- a/README.md
+++ b/README.md
@@ -18,7 +18,7 @@
The sdbusplus library is built using meson.
-```
+```sh
meson build
cd build
ninja
@@ -32,7 +32,7 @@
The sdbus++ application is installed as a standard Python package
using `setuptools`.
-```
+```sh
cd tools
./setup.py install
```
@@ -41,13 +41,14 @@
The sdbusplus library builds on top of the
[sd-bus](http://0pointer.net/blog/the-new-sd-bus-api-of-systemd.html)
-library to create a modern C++ API for D-Bus. The library attempts to be
+library to create a modern C++ API for D-Bus. The library attempts to be
as lightweight as possible, usually compiling to exactly the sd-bus API
calls that would have been necessary, while also providing compile-time
type-safety and memory leak protection afforded by modern C++ practices.
Consider the following code:
-```
+
+```cpp
auto b = bus::new_default_system();
auto m = b.new_method_call("org.freedesktop.login1",
"/org/freedesktop/login1",
@@ -61,36 +62,36 @@
In a few, relatively succinct, C++ lines this snippet will create a D-Bus
connection to the system bus, and call the systemd login manager to get a
-list of active users. The message and bus objects are automatically freed
+list of active users. The message and bus objects are automatically freed
when they leave scope and the message format strings are generated at compile
-time based on the types being read. Compare this to the corresponding server
+time based on the types being read. Compare this to the corresponding server
code within [logind](https://github.com/systemd/systemd/blob/d60c527009133a1ed3d69c14b8c837c790e78d10/src/login/logind-dbus.c#L496).
In general, the library attempts to mimic the naming conventions of the sd-bus
library: ex. `sd_bus_call` becomes `sdbusplus::bus::call`,
`sd_bus_get_unique_name` becomes `sdbusplus::bus::get_unique_name`,
`sd_bus_message_get_signature` becomes `sdbusplus::message::get_signature`,
-etc. This allows a relatively straight-forward translation back to the sd-bus
+etc. This allows a relatively straight-forward translation back to the sd-bus
functions for looking up the manpage details.
## Binding generation tool
-sdbusplus also contains a bindings generator tool: `sdbus++`. The purpose of
+sdbusplus also contains a bindings generator tool: `sdbus++`. The purpose of
a bindings generator is to reduce the boilerplate associated with creating
-D-Bus server or client applications. When creating a server application,
+D-Bus server or client applications. When creating a server application,
rather than creating sd-bus vtables and writing C-style functions to handle
each vtable callback, you can create a small YAML file to define your D-Bus
interface and the `sdbus++` tool will create a C++ class that implements your
-D-Bus interface. This class has a set of virtual functions for each method
+D-Bus interface. This class has a set of virtual functions for each method
and property, which you can overload to create your own customized behavior
for the interface.
There are currently two types of YAML files: [interface](docs/interface.md) and
-[error](docs/error.md). Interfaces are used to create server and client D-Bus
-interfaces. Errors are used to define C++ exceptions which can be thrown and
+[error](docs/error.md). Interfaces are used to create server and client D-Bus
+interfaces. Errors are used to define C++ exceptions which can be thrown and
will automatically turn into D-Bus error responses.
-[[ D-Bus client bindings are not yet implemented. See openbmc/openbmc#851. ]]
+[[D-Bus client bindings are not yet implemented. See openbmc/openbmc#851.]]
### Generating bindings
@@ -101,7 +102,8 @@
`org/freedesktop/Example.interface.yaml` and
`org/freedesktop/Example.errors.yaml]` for interfaces and errors respectively.
These can then be used to generate the server and error bindings:
-```
+
+```sh
sdbus++ interface server-header org.freedesktop.Example > \
org/freedesktop/Example/server.hpp
sdbus++ interface server-cpp org.freedesktop.Example > \
@@ -114,7 +116,8 @@
Markdown-based documentation can also be generated from the interface and
exception files:
-```
+
+```sh
sdbus++ interface markdown org.freedesktop.Example > \
org/freedesktop/Example.md
sdbus++ error markdown org.freedesktop.Example >> \
@@ -132,17 +135,20 @@
### Installation on Ubuntu
-```
-sudo apt install git meson libtool pkg-config g++ libsystemd-dev python3 python3-pip python3-yaml python3-mako python3-inflection
+```sh
+sudo apt install git meson libtool pkg-config g++ libsystemd-dev \
+ python3 python3-pip python3-yaml python3-mako python3-inflection
```
### Installation on Fedora
-```
-sudo dnf install git meson libtool gcc-c++ pkgconfig systemd-devel python3 python3-pip python3-yaml python3-mako
-```
-Install the inflection package using the pip utility (on Fedora)
-```
-pip3 install inflection
+```sh
+sudo dnf install git meson libtool gcc-c++ pkgconfig systemd-devel \
+ python3 python3-pip python3-yaml python3-mako
```
+Install the inflection package using the pip utility (on Fedora)
+
+```sh
+pip3 install inflection
+```
diff --git a/docs/error.md b/docs/error.md
index 5f9b62d..4177547 100644
--- a/docs/error.md
+++ b/docs/error.md
@@ -3,10 +3,10 @@
D-Bus errors can be defined by creating a YAML file to describe the errors.
From this YAML file, both documentation and binding code may be generated.
The generated bindings are C++ exception types corresponding to the D-Bus
-error name. Ex. `org.freedesktop.Example.Error.SomeError` will create a
+error name. Ex. `org.freedesktop.Example.Error.SomeError` will create a
generated exception type of
`sdbusplus::org::freedesktop::Example::Error::SomeError` which may be thrown
-or caught as appropriate. If the error is thrown from an interface method
+or caught as appropriate. If the error is thrown from an interface method
which has specified it may return that error, then the bindings will generate
a catch clause that returns a D-Bus error like
"org.freedesktop.Example.Error.SomeError" to the method caller.
@@ -14,11 +14,11 @@
The error YAML is simply a list of `name` along with optional `description`
and `errno` properties.
Example:
-```
+
+```yaml
- name: SomeError
- name: AnotherError
description: >
This is another error.
errno: E2BIG
```
-
diff --git a/docs/interface.md b/docs/interface.md
index 32c810e..0579ee7 100644
--- a/docs/interface.md
+++ b/docs/interface.md
@@ -1,31 +1,31 @@
# Interface YAML
D-Bus interfaces can be defined by creating a YAML file to describe the
-methods, properties, and signals they contain. From this YAML file,
+methods, properties, and signals they contain. From this YAML file,
both documentation and binding code may be generated.
## YAML sections
An interface YAML may have the following sections:
-* description
- - A small documentation section describing the purpose of the
- interface.
-* methods
- - A list of methods provided by this D-Bus interface.
-* properties
- - A list of properties provided by this D-Bus interface.
-* signals
- - A list of signals generated by this D-Bus interface.
-* enumerations
- - A list of enumerations defined by this D-Bus interface.
+- description
+ - A small documentation section describing the purpose of the
+ interface.
+- methods
+ - A list of methods provided by this D-Bus interface.
+- properties
+ - A list of properties provided by this D-Bus interface.
+- signals
+ - A list of signals generated by this D-Bus interface.
+- enumerations
+ - A list of enumerations defined by this D-Bus interface.
## Enumerations
A common problem we have found with D-Bus interfaces is having a consistent
-way to define enumerations. Two common practices are to either assign
+way to define enumerations. Two common practices are to either assign
special meaning to integers, as a C compiler might do, or to have specific
-strings representing the enumeration name. The [D-Bus API design guidelines](https://dbus.freedesktop.org/doc/dbus-api-design.html)
+strings representing the enumeration name. The [D-Bus API design guidelines](https://dbus.freedesktop.org/doc/dbus-api-design.html)
specify both of these options:
> For APIs being used in constrained situations, enumerated values should be
@@ -34,102 +34,104 @@
> values should be strings in some defined format.
What we have done in `sdbus++` is to consider enumerations as a first-class
-type. Within an interface you can define an enumeration and the bindings
-will have a C++ enumeration defined for it. At a D-Bus level any property or
+type. Within an interface you can define an enumeration and the bindings
+will have a C++ enumeration defined for it. At a D-Bus level any property or
method parameter will be a string, but the string will contain a
fully-qualified name "interface.enum-name.enum-value" like
-"org.freedesktop.Example.Color.Red". Within the generated bindings, an
+"org.freedesktop.Example.Color.Red". Within the generated bindings, an
automatic conversion is done between strings and C++ enumeration values and
clients will get an "xyz.openbmc_project.sdbusplus.Error.InvalidEnumString"
error response if they attempt to use an invalid string value.
An enumeration must have the YAML properties `name` and `values` and may
-optionally contain a `description`. The `name` is a word corresponding to
+optionally contain a `description`. The `name` is a word corresponding to
the desired "enum-name" portion of the fully-qualified name and the resulting
-C++ enum type. The `values` are a list of enumeration values each containing
+C++ enum type. The `values` are a list of enumeration values each containing
their own `name` and optional `description`.
Example:
-```
+
+```yaml
enumerations:
- - name: Suits
- description: >
- The suits found in a deck of cards.
- values:
- - name: Diamonds
- - name: Hearts
- - name: Clubs
- description: >
- This is the suit that looks like a clover.
- - name: Spades
+ - name: Suits
+ description: >
+ The suits found in a deck of cards.
+ values:
+ - name: Diamonds
+ - name: Hearts
+ - name: Clubs
+ description: >
+ This is the suit that looks like a clover.
+ - name: Spades
```
## Types
### Base types
+
Types are identified in YAML using their typename found in the
[D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html),
but listed using lowercases: `int64` instead of `INT64` or C++ `int64_t`.
-* byte
-* boolean
-* int16
-* uint16
-* ...
-* uint64
-* size - maps to the C 'size_t' for the architecture.
-* ssize - maps to the C 'ssize_t' for the architecture.
-* double
-* unixfd
-* string
-* object_path
-* signature
+- `byte`
+- `boolean`
+- `int16`
+- `uint16`
+- ...
+- `uint64`
+- `size` - maps to the C `size_t` for the architecture.
+- `ssize` - maps to the C `ssize_t` for the architecture.
+- `double`
+- `unixfd`
+- `string`
+- `object_path`
+- `signature`
### Special type values
+Note: The special value identifiers are all case-insensitive.
+
For floating-point types it is possible to express one of the special values:
- * 'NaN' (case-insensitive)
- - A quiet-type not-a-number value.
- * 'Infinity' (case-insensitive)
- - A positive infinity value.
- * '-Infinity' (case-insensitive)
- - A negative infinity value.
- * 'Epsilon' (case-insensitive)
- - An epsilon value.
+
+- `NaN` - A quiet-type not-a-number value.
+- `Infinity` : A positive infinity value.
+- `-Infinity` : A negative infinity value.
+- `Epsilon` : An epsilon value.
For integer types it is possible to express one of the special values:
- * 'minint' (case-insensitive)
- - The mininum value the integer type can hold.
- * 'maxint' (case-insensitive)
- - The maximum value the integer type can hold.
-### Containers
+- `minint` - The mininum value the integer type can hold.
+- `maxint` - The maximum value the integer type can hold.
+
+### Container Types
+
Container types can also be expressed, but the contained-type should be
-expressed within square-brackets `[]`. The following containers are supported:
+expressed within square-brackets `[]`. The following containers are supported:
-* `array[type]`
- - C++ type is `std::vector`
-* `dict[keytype, valuetype]`
- - C++ type is `std::map`
-* `set[type]`
- - C++ type is `std::set`
-* `struct[type0, type1, ...]`
- - C++ type is `std::tuple`
-* `variant[type0, type1, ...]`
- - C++ type is `std::variant`
+- `array[type]`
+ - C++ type is `std::vector`
+- `dict[keytype, valuetype]`
+ - C++ type is `std::map`
+- `set[type]`
+ - C++ type is `std::set`
+- `struct[type0, type1, ...]`
+ - C++ type is `std::tuple`
+- `variant[type0, type1, ...]`
+ - C++ type is `std::variant`
It may seem odd that variants are required to list the types they may contain,
-but this is due to C++ being a strongly-typed language. In order to generate
+but this is due to C++ being a strongly-typed language. In order to generate
bindings, to read from and append to a message, the binding generator must
know all possible types the variant may contain.
-### Enumerations
+### Enumeration Types
+
Enumerations are expressed like a container, but the contained-type is an
identifier of the fully-qualified enum-name or a shortened `self.` identifier
for locally defined types.
-* enum[org.freedesktop.Example.Suits]
-* enum[self.Suits]
+- enum[org.freedesktop.Example.Suits]
+- enum[self.Suits]
## Methods
@@ -145,29 +147,30 @@
return, which must be defined in a corresponding errors YAML file.
Example:
-```
+
+```yaml
methods:
- - name: Shuffle
- flags:
- - unprivileged
- errors:
- - self.Error.TooTired
- - name: Deal
- description: >
- Deals a new hand to each player.
- errors:
- - self.Error.OutOfCards
- - name: LookAtTop
- returns:
- - name: Card
- type: struct[enum[self.Suit], byte]
- - name: MoveToTop
- flags:
- - deprecated
- - no_reply
- parameters:
- - name: Card
- type: struct[enum[self.Suit], byte]
+ - name: Shuffle
+ flags:
+ - unprivileged
+ errors:
+ - self.Error.TooTired
+ - name: Deal
+ description: >
+ Deals a new hand to each player.
+ errors:
+ - self.Error.OutOfCards
+ - name: LookAtTop
+ returns:
+ - name: Card
+ type: struct[enum[self.Suit], byte]
+ - name: MoveToTop
+ flags:
+ - deprecated
+ - no_reply
+ parameters:
+ - name: Card
+ type: struct[enum[self.Suit], byte]
```
## Properties
@@ -179,52 +182,54 @@
The supported values for `flags` are and their equivalent sd-bus flag setting:
-* `deprecated` - SD_BUS_VTABLE_DEPRECATED
-* `hidden` - SD_BUS_VTABLE_HIDDEN
-* `unprivileged` - SD_BUS_VTABLE_UNPRIVILEGED
-* `const` - SD_BUS_VTABLE_PROPERTY_CONST
-* `emits_change` - SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE
-* `emits_invalidation` - SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION
-* `explicit` - SD_BUS_VTABLE_PROPERTY_EXPLICIT
-* `readonly` - (N/A)
+- `deprecated` - SD_BUS_VTABLE_DEPRECATED
+- `hidden` - SD_BUS_VTABLE_HIDDEN
+- `unprivileged` - SD_BUS_VTABLE_UNPRIVILEGED
+- `const` - SD_BUS_VTABLE_PROPERTY_CONST
+- `emits_change` - SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE
+- `emits_invalidation` - SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION
+- `explicit` - SD_BUS_VTABLE_PROPERTY_EXPLICIT
+- `readonly` - (N/A)
If no flag is given, a property will default to `emits_change`.
Both `const` and `readonly` prevent D-Bus clients from being able to write
-to a property. `const` is a D-Bus indication that the property can never
+to a property. `const` is a D-Bus indication that the property can never
change, while `readonly` properties can be changed by the D-Bus server itself.
As examples, the `Version` property on a software object might be appropriate
to be `const` and the `Value` property on a sensor object would likely be
`readonly`.
Example:
-```
+
+```yaml
properties:
- - name: CardsRemaining
- type: uint32
- default: 52
- flags:
- - const
- description: >
- The number of cards remaining in the deck.
- errors:
- - self.Error.InvalidNumber
+ - name: CardsRemaining
+ type: uint32
+ default: 52
+ flags:
+ - const
+ description: >
+ The number of cards remaining in the deck.
+ errors:
+ - self.Error.InvalidNumber
```
## Signals
A signal must have the YAML property `name` and may optionally have a
-`description` and list of `properties`. Properties are specified the same
+`description` and list of `properties`. Properties are specified the same
as interface properties.
Example:
-```
+
+```yaml
signals:
- - name: Shuffled
- description: >
- The deck has been shuffled.
- - name: Cheated
- properties:
- - name: CardToTop
- type: struct[enum[self.Suit], byte]
+ - name: Shuffled
+ description: >
+ The deck has been shuffled.
+ - name: Cheated
+ properties:
+ - name: CardToTop
+ type: struct[enum[self.Suit], byte]
```
diff --git a/include/sdbusplus/server/README.md b/include/sdbusplus/server/README.md
index c369b57..234df71 100644
--- a/include/sdbusplus/server/README.md
+++ b/include/sdbusplus/server/README.md
@@ -16,13 +16,13 @@
**How is _transaction id_ used** - Used to identify all the journal entries
associated with a dbus operation.
-* When a journal entry is created, the _transaction id_ is added as metadata.
-Therefore all journal entries created within a message have the same
-_transaction id_ value.
+- When a journal entry is created, the _transaction id_ is added as metadata.
+ Therefore all journal entries created within a message have the same
+ _transaction id_ value.
-* When an error/event log is created, the _transaction id_ of that message will
-be used to collect the journal entries associated with that message, providing
-debug information for the complete operation.
+- When an error/event log is created, the _transaction id_ of that message will
+ be used to collect the journal entries associated with that message, providing
+ debug information for the complete operation.
**Multiple _transaction ids_** - The exception object can store multiple
_transaction ids_ for operations that create multiple messages.