DRM Docbook is now Markdown ready. This means its doc is able to
use markdown text on it.
* Documentation/DocBook/drm.tmpl: Contains a table duplicated from
drivers/gpu/drm/i915/i915_reg.h. This is not needed anymore
* drivers/gpu/drm/drm_modeset_lock.c: had a code example that used
to look pretty bad on html. Fixed by using proper code markup.
* drivers/gpu/drm/drm_prime.c: Remove spaces between lines to make
a proper markup list.
* drivers/gpu/drm/i915/i915_reg.h: Altought pandoc supports tables,
it doesn't support table cell spanning. But we can use fixed-width
for those special cases.
* include/drm/drm_vma_manager.h: Another code example that should be
proper indented with four spaces.
v2 (Daniel): Adjust name to gpu.xml due to rename.
v3 (Daniel):
Split out the actual enabling in the Makefile - this way we can merge
the conversion, while just keeping the enabling in a drm-private tree.
Signed-off-by: Danilo Cesar Lemes de Paula <[email protected]> (v1)
Cc: Randy Dunlap <[email protected]>
Cc: Daniel Vetter <[email protected]>
Cc: Laurent Pinchart <[email protected]>
Cc: Jonathan Corbet <[email protected]>
Cc: Herbert Xu <[email protected]>
Cc: Stephan Mueller <[email protected]>
Cc: Michal Marek <[email protected]>
Cc: [email protected]
Cc: [email protected]
Cc: intel-gfx <[email protected]>
Cc: dri-devel <[email protected]>
Acked-by: Dave Airlie <[email protected]>
Signed-off-by: Daniel Vetter <[email protected]>
Link: http://patchwork.freedesktop.org/patch/msgid/[email protected]
The "highlight" code is very sensible to the order of the hash keys,
but the order of the keys cannot be predicted. It generates
faulty DocBook entries like:
- @<function>device_for_each_child</function>
Sorting the result is not enough some times (as it's deterministic but
we can't control it).
We should use an array for that job, so we can guarantee that the order
of the regex execution on dohighlight is correct.
[jc: I think this is kind of papering around the real problem, that people
are saying @function() when "function" is not a parameter. But this makes
things better than they were before, so...]
Signed-off-by: Danilo Cesar Lemes de Paula <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Docproc processes the EXPORT_SYMBOL(f1) macro and uses -nofunc f1 to
avoid duplicated documentation in the next call.
It works for most of the cases, but there are some specific situations
where a struct has the same name of an already-exported function.
Current kernel-doc behavior ignores those structs and does not add them
to the final documentation. This patch fixes it.
This is unusual, the only case I've found is the drm_modeset_lock
(function and struct) defined in drm_modeset_lock.h and
drm_modeset_lock.c. Considering this, it should only affect the DRM
documentation by including struct drm_modeset_lock to the final Docbook.
Signed-off-by: Danilo Cesar Lemes de Paula <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Functions, Structs and Parameters definitions on kernel documentation
are pure cosmetic, it only highlights the element.
To ease the navigation in the documentation we should use <links> inside
those tags so readers can easily jump between methods directly.
This was discussed in 2014[1] and is implemented by getting a list
of <refentries> from the DocBook XML to generate a database. Then it looks
for <function>,<structnames> and <paramdef> tags that matches the ones in
the database. As it only links existent references, no broken links are
added.
[1] - lists.freedesktop.org/archives/dri-devel/2014-August/065404.html
Signed-off-by: Danilo Cesar Lemes de Paula <[email protected]>
Cc: Randy Dunlap <[email protected]>
Cc: Daniel Vetter <[email protected]>
Cc: Laurent Pinchart <[email protected]>
Cc: Herbert Xu <[email protected]>
Cc: Stephan Mueller <[email protected]>
Cc: Michal Marek <[email protected]>
Cc: intel-gfx <[email protected]>
Cc: dri-devel <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Describing arguments at top of a struct definition works fine
for small/medium size structs, but it definitely doesn't work well
for struct with a huge list of elements.
Keeping the arguments list inside the struct body makes it easier
to maintain the documentation.
ie:
/**
* struct my_struct - short description
* @a: first member
* @b: second member
*
* Longer description
*/
struct my_struct {
int a;
int b;
/**
* @c: This is longer description of C
*
* You can use paragraphs to describe arguments
* using this method.
*/
int c;
};
This patch allows the use of this kind of syntax. Only one argument
per comment and user can use how many paragraphs he needs. It should
start with /**, which is already being used by kernel-doc. If those
comment doesn't follow those rules, it will be ignored.
Signed-off-by: Danilo Cesar Lemes de Paula <[email protected]>
Cc: Randy Dunlap <[email protected]>
Cc: Daniel Vetter <[email protected]>
Cc: Laurent Pinchart <[email protected]>
Cc: Jonathan Corbet <[email protected]>
Cc: Herbert Xu <[email protected]>
Cc: Stephan Mueller <[email protected]>
Cc: Michal Marek <[email protected]>
Cc: [email protected]
Cc: [email protected]
Cc: intel-gfx <[email protected]>
Cc: dri-devel <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Danilo Cesar Lemes de Paula