Am 23.08.2016 um 16:43 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>: > Em Mon, 22 Aug 2016 14:57:40 -0600 > Jonathan Corbet <corbet@xxxxxxx> escreveu: > >> This short series convers device-drivers.tmpl into the RST format, splits >> it up, and sets up the result under Documentation/driver-api/. For added >> fun, I've taken one top-level file (hsi.txt) and folded it into the >> document as a way of showing the direction I'm thinking I would like things >> to go. There is plenty more of this sort of work that could be done, to >> say the least - this is just a beginning! >> >> The formatted results can be seen at: >> >> http://static.lwn.net/kerneldoc/driver-api/index.html > > Thanks for doing that! IMHO, the conversion of this book is indeed > one of the first things to be done. >> As part of the long-term task to turn Documentation/ into less of a horror >> movie, I'd like to collect documentation of the driver-specific API here. Hi, here are my 2cent, about the *generic* content from the kernel-doc directive: .. kernel-doc:: kernel/sched/core.c :export: IMHO directives like the one above are to *generic*. If I read this directive I would expect, that all exported symbols are documented. But this is a false estimation! In my POC I use a more restrictive kernel-doc parser (https://github.com/return42/linuxdoc). For the directive above the parser logs, that some of the exported symbols are not found / not documented: $ kernel-doc --quiet --list-exports kernel/sched/core.c [exported undocumented ] set_cpus_allowed_ptr [exported undocumented ] kick_process [exported function ] wake_up_process [exported undocumented ] preempt_notifier_inc [exported undocumented ] preempt_notifier_dec [exported function ] preempt_notifier_register [exported function ] preempt_notifier_unregister [exported undocumented ] single_task_running [exported undocumented ] preempt_count_add [exported undocumented ] preempt_count_sub [exported undocumented ] schedule [exported undocumented ] preempt_schedule [exported function ] preempt_schedule_notrace [exported undocumented ] default_wake_function [exported undocumented ] set_user_nice [exported function ] sched_setscheduler [exported undocumented ] sched_setattr [exported function ] sched_setscheduler_nocheck [exported undocumented ] _cond_resched [exported undocumented ] __cond_resched_lock [exported undocumented ] __cond_resched_softirq [exported function ] yield [exported function ] yield_to [exported undocumented ] io_schedule_timeout [exported undocumented ] __might_sleep [exported undocumented ] ___might_sleep The driver-api is full of *generic* content and IMHO it is not really clear what would be a part of the resulting documentation. To illustrate, you can take a look on the (old) *automatic* conversion of mine at: http://return42.github.io/sphkerneldoc/books/device-drivers/index.html There you see a list of 'Oops: Document generation inconsistency.' This kind of missing documentation grows up with changes to the source files while there are no errors reported. What I mean: in most use cases it is better to be explicit and name the functions, structs or whatever which should be a part of the documentation. e.g.:: .. kernel-doc:: kernel/sched/core.c :functions: wake_up_process yield ... By being explicit, the kernel-doc parser has a chance to identify requested but missing documentation and log related error messages. Summarized: - *explicit* is better than implicit. - the *generic* part of kernel-doc parser should more restrictive These are my thoughts, even if we do nothing to handle it, we should aware about this. -- Markus -- > >> Arguably gpu/ and the media API stuff should eventually move here, though >> we can discuss the color of that particular shed some other day. > > Yeah, let's finish converting everything to rst, and then see what would > be the best way to organize it. > > I have a split feelings with regards to media kAPI and driver-specific > stuff if it is better to keep it at the device-drivers book, or at a > single media book (with currently has 1031 pages on PDF output), > but let's postpone such discussion. > > I'm afraid that we'll end needing to split it more than what would be > desired, in order to fix some issues with the PDF output > part/chapter/section numbering. Unfortunately, ReST markup is too poor > to describe multi-part books, and doesn't have anything to describe > multi-book projects. > >> Meanwhile, I'd appreciate comments on the general idea. > > I like the general idea of breaking device-drivers.tmpl into multiple > files. IMHO, that will make easier to maintain it long term. > > After looking on all 3 patches, they all look good, as a concept. > > Yet, IMHO, there are a few things to be fixed before merging it. See > my comments to patch 2/3. > > Regards, > Mauro > >> >> Cc: Jani Nikula <jani.nikula@xxxxxxxxx> >> Cc: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> >> Cc: Sebastian Reichel <sre@xxxxxxxxxx> >> >> Jonathan Corbet (3): >> Docs: sphinxify device-drivers.tmpl >> docs: split up the driver book >> docs: Pull HSI documentation together >> >> Documentation/DocBook/Makefile | 2 +- >> Documentation/DocBook/device-drivers.tmpl | 521 ------------------------- >> Documentation/driver-api/basics.rst | 120 ++++++ >> Documentation/driver-api/frame-buffer.rst | 62 +++ >> Documentation/driver-api/index.rst | 24 ++ >> Documentation/driver-api/infrastructure.rst | 169 ++++++++ >> Documentation/driver-api/input.rst | 51 +++ >> Documentation/driver-api/message-based.rst | 30 ++ >> Documentation/driver-api/miscellaneous.rst | 50 +++ >> Documentation/driver-api/serial-interfaces.rst | 189 +++++++++ >> Documentation/driver-api/sound.rst | 54 +++ >> Documentation/hsi.txt | 75 ---- >> Documentation/index.rst | 1 + >> MAINTAINERS | 2 +- >> 14 files changed, 752 insertions(+), 598 deletions(-) >> delete mode 100644 Documentation/DocBook/device-drivers.tmpl >> create mode 100644 Documentation/driver-api/basics.rst >> create mode 100644 Documentation/driver-api/frame-buffer.rst >> create mode 100644 Documentation/driver-api/index.rst >> create mode 100644 Documentation/driver-api/infrastructure.rst >> create mode 100644 Documentation/driver-api/input.rst >> create mode 100644 Documentation/driver-api/message-based.rst >> create mode 100644 Documentation/driver-api/miscellaneous.rst >> create mode 100644 Documentation/driver-api/serial-interfaces.rst >> create mode 100644 Documentation/driver-api/sound.rst >> delete mode 100644 Documentation/hsi.txt >> > > > > Thanks, > Mauro > -- > To unsubscribe from this list: send the line "unsubscribe linux-doc" in > the body of a message to majordomo@xxxxxxxxxxxxxxx > More majordomo info at http://vger.kernel.org/majordomo-info.html -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
