From ae774e2c68d19da7a8e982889a5a1684cac93c78 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Thu, 29 Dec 2016 11:44:35 +0100 Subject: drm/doc: link style-guide to doc-guide Our style guide should only be the delta compared to the overall one. Cc: Chris Wilson Reviewed-by: Chris Wilson Signed-off-by: Daniel Vetter Link: http://patchwork.freedesktop.org/patch/msgid/1483008275-29383-1-git-send-email-daniel.vetter@ffwll.ch --- Documentation/gpu/introduction.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation/gpu/introduction.rst') diff --git a/Documentation/gpu/introduction.rst b/Documentation/gpu/introduction.rst index 1903595b5310..6960e31f71e1 100644 --- a/Documentation/gpu/introduction.rst +++ b/Documentation/gpu/introduction.rst @@ -49,3 +49,5 @@ section name should be all upper-case or not, and whether it should end in a colon or not. Go with the file-local style. Other common section names are "Notes" with information for dangerous or tricky corner cases, and "FIXME" where the interface could be cleaned up. + +Also read the :ref:`guidelines for the kernel documentation at large `. -- cgit v1.2.3 From f5a8d8774bbb81c64073c1e29ce29cfa3d044f83 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Thu, 29 Dec 2016 21:48:28 +0100 Subject: drm/doc: Update styleguide The new cool is &struct foo (kernel-doc now copes with linebreaks), and structure members should be referenced using &foo.bar. Cc: Jani Nikula Cc: Chris Wilson Reviewed-by: David Herrmann Signed-off-by: Daniel Vetter Link: http://patchwork.freedesktop.org/patch/msgid/1483044517-5770-8-git-send-email-daniel.vetter@ffwll.ch --- Documentation/gpu/introduction.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) (limited to 'Documentation/gpu/introduction.rst') diff --git a/Documentation/gpu/introduction.rst b/Documentation/gpu/introduction.rst index 6960e31f71e1..eb284eb748ba 100644 --- a/Documentation/gpu/introduction.rst +++ b/Documentation/gpu/introduction.rst @@ -23,13 +23,12 @@ For consistency this documentation uses American English. Abbreviations are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so on. To aid in reading, documentations make full use of the markup characters kerneldoc provides: @parameter for function parameters, -@member for structure members, &structure to reference structures and -function() for functions. These all get automatically hyperlinked if -kerneldoc for the referenced objects exists. When referencing entries in -function vtables please use ->vfunc(). Note that kerneldoc does not -support referencing struct members directly, so please add a reference -to the vtable struct somewhere in the same paragraph or at least -section. +@member for structure members (within the same structure), &struct structure to +reference structures and function() for functions. These all get automatically +hyperlinked if kerneldoc for the referenced objects exists. When referencing +entries in function vtables (and structure members in general) please use +&vtable_name.vfunc. Unfortunately this does not yet yield a direct link to the +member, only the structure. Except in special situations (to separate locked from unlocked variants) locking requirements for functions aren't documented in the kerneldoc. -- cgit v1.2.3