On Thu, May 07, 2020 at 02:55:24PM +0200, Peter Krempa wrote: > On Thu, May 07, 2020 at 14:46:38 +0200, Andrea Bolognani wrote: > > Signed-off-by: Andrea Bolognani <abologna@xxxxxxxxxx> > > --- > > docs/coding-style.rst | 53 +++++++++++------- > > docs/glib-adoption.rst | 123 +++++++++++++++++++++++++++-------------- > > 2 files changed, 114 insertions(+), 62 deletions(-) > > > > diff --git a/docs/coding-style.rst b/docs/coding-style.rst > > index 151ea87b6a..15c3a0b22d 100644 > > --- a/docs/coding-style.rst > > +++ b/docs/coding-style.rst > > @@ -547,27 +547,38 @@ Attribute annotations > > Use the following annotations to help the compiler and/or static > > analysis tools understand the code better: > > > > -+-------------------------------+------------------------------------------------------------+ > > -| Macro | Meaning | > > -+===============================+============================================================+ > > -| ``ATTRIBUTE_NONNULL`` | passing NULL for this parameter is not allowed | > > -+-------------------------------+------------------------------------------------------------+ > > -| ``ATTRIBUTE_PACKED`` | force a structure to be packed | > > -+-------------------------------+------------------------------------------------------------+ > > -| ``G_GNUC_FALLTHROUGH`` | allow code reuse by multiple switch cases | > > -+-------------------------------+------------------------------------------------------------+ > > -| ``G_GNUC_NO_INLINE`` | the function is mocked in the test suite | > > -+-------------------------------+------------------------------------------------------------+ > > -| ``G_GNUC_NORETURN`` | the function never returns | > > -+-------------------------------+------------------------------------------------------------+ > > -| ``G_GNUC_NULL_TERMINATED`` | last parameter must be NULL | > > -+-------------------------------+------------------------------------------------------------+ > > -| ``G_GNUC_PRINTF`` | validate that the formatting string matches parameters | > > -+-------------------------------+------------------------------------------------------------+ > > -| ``G_GNUC_UNUSED`` | parameter is unused in this implementation of the function | > > -+-------------------------------+------------------------------------------------------------+ > > -| ``G_GNUC_WARN_UNUSED_RESULT`` | the return value must be checked | > > -+-------------------------------+------------------------------------------------------------+ > > +.. list-table:: > > + :header-rows: 1 > > + > > + * - Macro > > + - Meaning > > + > > + * - ``ATTRIBUTE_NONNULL`` > > + - passing NULL for this parameter is not allowed > > Well, the ascii-art version is more readable when looking at the text > version. I think there's probably a tradeoff to be had, based on the complexity and size of the table. For only simple tables where each line is less than 80 chars, and only 1 line high per row, then the ascii-art table is visually nicer. For tables where we're likely to exceed 80 chars, the list-table is probably better choice, otherwise things just get too wide. In this particular case, I think we didn't need a table at all in the first place. It would be fine as a "definition list". Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
