lkml.org 
[lkml]   [2018]   [May]   [10]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    From
    SubjectRe: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings
    Em Thu, 10 May 2018 18:52:20 +0200
    Andrea Parri <andrea.parri@amarulasolutions.com> escreveu:

    > On Thu, May 10, 2018 at 07:15:59AM -0600, Jonathan Corbet wrote:
    > > On Thu, 10 May 2018 14:23:35 +0200
    > > Andrea Parri <andrea.parri@amarulasolutions.com> wrote:
    > >
    > > > only
    > > > remember that other people (including some developers running into the
    > > > "disadventure" of opening an RST doc. from their preferred text editor
    > > > and being brought to conclude: "WTH! I need to open a web browser, I
    > > > guess...") _use_ such doc. and _do care_ about it, and that what might
    > > > be an improvement for some people might look as "vandalizing" to others.
    > >
    > > If you have an example of a place where use of a web browser has been
    > > made mandatory, please point it out. Avoiding that was at the top of the
    > > list of explicit requirements.
    >
    > That's all I need.
    >
    >
    > >Surely an extra colon is not going to
    > > force you to run screaming to the protective embrace of Firefox...?
    >
    > Let me put it in these terms: I believe that that extra colon (or the
    > "diagram" keywork) is not going to improve/help my use of the doc. ;D

    No, it won't improve, but, it won't make it harder for a human
    to understand if a "diagram" or "::" is added at the description.

    The thing is that we need something that works for the Kernel as
    a hole, and not just on a few places.

    On some subsystems, just a text is not good enough to describe
    things. See, for example:
    https://www.kernel.org/doc/html/latest/media/uapi/v4l/crop.html
    https://www.kernel.org/doc/html/latest/media/uapi/v4l/pixfmt-packed-rgb.html
    https://www.kernel.org/doc/html/latest/media/uapi/v4l/pixfmt-srggb10-ipu3.html
    https://www.kernel.org/doc/html/latest/gpu/drm-kms.html

    Images, complex tables, etc are sometimes required to show some things.
    Trying to explain just on text is harder to write, longer and worse
    for readers. In the past, DocBook was used. ReST made very simple to
    write documentation. From where I sit, I'm reviewing documentation
    patches from a lot more people than the usage of a markup language.

    As a bonus, we can now create cross-references for kernel-doc functions,
    with is really great when reading documentation for complex hardware.

    From where I sit at media, the subsystem documentation, if generated
    in PDF, becomes a book with more than 1,100 pages, full of long tables,
    images and graphs[1], covering uAPI, kAPI and driver-specific
    documentation.

    [1] https://linuxtv.org/downloads/v4l-dvb-apis-new/media.pdf

    As on all subsystems, developers write documentation directly
    at .rst or as kernel-doc comments. But for reading it, even developers
    prefer to read the docs via the html (or pdf) output, as it better
    shows tables and images. It is also faster to follow the dozen
    thousands of links inside it.

    The point is: we shouldn't enforce everyone to use our own view
    about how to navigate through documentation. People are free to
    use whatever improves their workflow.

    Thanks,
    Mauro

    \
     
     \ /
      Last update: 2018-05-10 19:46    [W:3.843 / U:0.032 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site