Conversation
jarkko

Jarkko Sakkinen

@jani, Didn't DRM documentation have some nice way to embed and include documentation from source files?

In vcam, I will have at least documentation blocks for theory of operation and very like locking hierarchy (depending on complexity). It would be nice to have in Documentation/ something that includes those snippets.

Just looking for tips and too lazy for RTFM ATM :-)
1
0
1
jani@floss.social

Jani Nikula

Reply to @jarkko

@jarkko It's not only DRM documentation, but all kernel documentation. We were just spearheading the whole thing originally.

Add this to path/to/source.c:

/**
* DOC: My cool overview
*
* (rst formatted documentation)
*/

And this to some .rst file under Documentation:

.. kernel-doc:: path/to/source.c
:doc: My cool overview

It'll slurp in the documentation from the source. Obvously you can also document functions etc. See the link below for more.

https://docs.kernel.org/doc-guide/kernel-doc.html

1
1
1
jarkko

Jarkko Sakkinen

Reply to @jani@floss.social
@jani thanks! better to take this approach now that i'm writing a completely new driver
0
0
1
About social.kernel.org

Terms of service

  1. Please do not use this service in violation of the Linux Kernel Code of Conduct. Doing so will result in your account suspension with the referral of the matter to the CoC committee.

  2. "Repeating"/"boosting" someone else's status on this platform will be treated as endorsement and will fall under rule #1.

  3. You are encouraged to use this platform to promote your work on the Linux Kernel, but there is no restriction on permitted topics (with the exception of anything covered by #1 above).

  4. There is no requirement to post in English, but it should be considered the primary language of communication on this platform.

Privacy notice

The admins of this service have access to all posted statuses. They aren't looking, but if it's something they shouldn't know about, then you should not post it on this platform.

Please see the Linux Foundation Privacy Policy, which applies to this platform as well.

Getting your own account

If you would like an account on this instance, please check that the following applies to you:

  • You are listed in MAINTAINERS or CREDITS

  • OR: You have a kernel.org account or email address

  • OR: You have a long and established history of involvement with the Linux Kernel

If the above is true and you agree with the Terms of Service and Privacy Notice listed above, please use these instructions to request an account: