Re: [Intel-gfx] [Mesa-dev] [PATCH v3 3/4] drm/i915/uapi: convert i915_query and friend to kernel doc

[Jonathan Corbet]

Daniel Vetter  writes:

> On Fri, Apr 16, 2021 at 12:25 AM Ian Romanick  wrote:
>> Since we just had a big discussion about this on mesa-dev w.r.t. Mesa
>> code and documentation... does the kernel have a policy about which
>> flavor (pun intended) of English should be used?
>
> I'm not finding it documented in
> https://dri.freedesktop.org/docs/drm/doc-guide/sphinx.html but I
> thought we've discussed it. Adding linux-doc and Jon Corbet.

It's in Documentation/doc-guide/contributing.rst:

> Please note that some things are *not* typos and should not be "fixed":
> 
>  - Both American and British English spellings are allowed within the
>kernel documentation.  There is no need to fix one by replacing it with
>the other.

Thanks,

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH v2] kernel-doc: rename the kernel-doc directive 'functions' to 'identifiers'

[Jonathan Corbet]

On Tue, 29 Oct 2019 08:31:22 +0800
Changbin Du  wrote:

> Here python is different from C. Both empty string and None are False in 
> python.
> Note such condition is common in python.

Treating both as a False value is reasonably common.  Treating them
elsewhere in the same code block as separate values is less
so; that's the part I would prefer to avoid.

Thanks,

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH v2] kernel-doc: rename the kernel-doc directive 'functions' to 'identifiers'

[Jonathan Corbet]

On Sun, 20 Oct 2019 21:17:17 +0800
Changbin Du  wrote:

> The 'functions' directive is not only for functions, but also works for
> structs/unions. So the name is misleading. This patch renames it to
> 'identifiers', which specific the functions/types to be included in
> documentation. We keep the old name as an alias of the new one before
> all documentation are updated.
> 
> Signed-off-by: Changbin Du 

So I think this is basically OK, but I have one more request...

[...]

> diff --git a/Documentation/sphinx/kerneldoc.py 
> b/Documentation/sphinx/kerneldoc.py
> index 1159405cb920..0689f9c37f1e 100644
> --- a/Documentation/sphinx/kerneldoc.py
> +++ b/Documentation/sphinx/kerneldoc.py
> @@ -59,9 +59,10 @@ class KernelDocDirective(Directive):
>  optional_arguments = 4
>  option_spec = {
>  'doc': directives.unchanged_required,
> -'functions': directives.unchanged,
>  'export': directives.unchanged,
>  'internal': directives.unchanged,
> +'identifiers': directives.unchanged,
> +'functions': directives.unchanged,  # alias of 'identifiers'
>  }
>  has_content = False
>  
> @@ -71,6 +72,7 @@ class KernelDocDirective(Directive):
>  
>  filename = env.config.kerneldoc_srctree + '/' + self.arguments[0]
>  export_file_patterns = []
> +identifiers = None
>  
>  # Tell sphinx of the dependency
>  env.note_dependency(os.path.abspath(filename))
> @@ -86,19 +88,22 @@ class KernelDocDirective(Directive):
>  export_file_patterns = str(self.options.get('internal')).split()
>  elif 'doc' in self.options:
>  cmd += ['-function', str(self.options.get('doc'))]
> +elif 'identifiers' in self.options:
> +identifiers = self.options.get('identifiers').split()
>  elif 'functions' in self.options:
> -functions = self.options.get('functions').split()
> -if functions:
> -for f in functions:
> -cmd += ['-function', f]
> -else:
> -cmd += ['-no-doc-sections']
> +identifiers = self.options.get('functions').split()

Rather than do this, can you just change the elif line to read:

elif ('identifiers' in self.options) or ('functions' in self.options):

...then leave the rest of the code intact?  It keeps the logic together,
and avoids the confusing distinction between identifiers=='' and
identifiers==None .

Thanks,

jon

>  for pattern in export_file_patterns:
>  for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern):
>  env.note_dependency(os.path.abspath(f))
>  cmd += ['-export-file', f]
>  
> +if identifiers:
> +for i in identifiers:
> +cmd += ['-function', i]
> +elif identifiers is not None:
> +cmd += ['-no-doc-sections']
> +
>  cmd += [filename]
>  
>  try:
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH] kernel-doc: rename the kernel-doc directive 'functions' to 'specific'

[Jonathan Corbet]

On Sun, 13 Oct 2019 13:53:59 +0800
Changbin Du  wrote:

> The 'functions' directive is not only for functions, but also works for
> structs/unions. So the name is misleading. This patch renames it to
> 'specific', so now we have export/internal/specific directives to limit
> the functions/types to be included in documentation. Meanwhile we improved
> the warning message.

I agree with the others that "specific" doesn't really make things
better.  "Interfaces" maybe; otherwise we could go for something like
"filter" or "select".

Paint mine green :)

Whatever we end up with, I think it should be added as a synonym for
"functions".  Then the various selectors that are actually pulling out
docs for functions could be changed at leisure - or not at all.  I'd
rather not see a big patch changing everything at once.

Thanks,

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH] docs: fix some broken references due to txt->rst renames

[Jonathan Corbet]

On Tue, 18 Jun 2019 10:33:58 -0300
Mauro Carvalho Chehab  wrote:

> here are three left-overs from the recent file renames,
> probably due to some other conflicting patch.
> 
> Fix them.
> 
> Signed-off-by: Mauro Carvalho Chehab 
> ---
> 
> This patch is against today's next-20190617 branch. Not sure if it
> will apply cleanly at -docs tree. If not,  Please let me know for me to
> split.

Indeed it does not; one of the files being patched doesn't even exist in
my world...

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH v5] docs: power: convert docs to ReST and rename to *.rst

[Jonathan Corbet]

On Thu, 13 Jun 2019 07:10:36 -0300
Mauro Carvalho Chehab  wrote:

> Convert the PM documents to ReST, in order to allow them to
> build with Sphinx.
> 
> The conversion is actually:
>   - add blank lines and identation in order to identify paragraphs;
>   - fix tables markups;
>   - add some lists markups;
>   - mark literal blocks;
>   - adjust title markups.
> 
> At its new index.rst, let's add a :orphan: while this is not linked to
> the main index.rst file, in order to avoid build warnings.
> 
> Signed-off-by: Mauro Carvalho Chehab 
> Acked-by: Mark Brown 
> Acked-by: Bjorn Helgaas 
> Acked-by: Srivatsa S. Bhat (VMware) 

So I can't apply this one due to conflicts in include/linux/pci.h.  Bjorn,
perhaps the easiest thing is for you to take this one through your tree?

Thanks,

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH 0/6] Add support for in-line nested struct comments

[Jonathan Corbet]

On Fri, 16 Feb 2018 11:48:14 -0200
Mauro Carvalho Chehab  wrote:

> his series fix two bugs at kernel-doc.rst examples and add support
> for in-line nested struct comments.
> 
> It also converts one documentation at intel_dpio_phy to use it,
> in order to give a practical example about how to use it.

OK, I've applied everything but the last patch, which I assume will go
through the DRM tree.

Thanks,

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH 1/5] dma-buf: Extract dma-buf.rst

[Jonathan Corbet]

On Fri,  9 Dec 2016 19:53:05 +0100
Daniel Vetter  wrote:

> Just prep work to polish and consolidate all the dma-buf related
> documenation.
> 
> Unfortunately I didn't discover a way to both integrate this new file
> into the overall toc while keeping it at the current place. Work
> around that by moving it into the overall driver-api/index.rst.

OK, I've applied this, with one change:

> diff --git a/include/linux/dma-fence.h b/include/linux/dma-fence.h
> index d51a7d23c358..c683c4e908d2 100644
> --- a/include/linux/dma-fence.h
> +++ b/include/linux/dma-fence.h
> @@ -163,7 +163,6 @@ struct dma_fence_cb {
>   * destruction of the fence. Can be called from irq context.
>   * If pointer is set to NULL, kfree will get called instead.
>   */
> -
>  struct dma_fence_ops {
>   const char * (*get_driver_name)(struct dma_fence *fence);
>   const char * (*get_timeline_name)(struct dma_fence *fence);

This hunk didn't apply to my tree, but I figured that, under duress, we
could probably manage to do without it for now...:)

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH 0/5] sphinxification for dma-buf docs

[Jonathan Corbet]

On Sun, 11 Dec 2016 18:35:42 +0100
Daniel Vetter  wrote:

> > Here's a thought, though: how about if we slip in a little version of
> > dma-buf.rst now with a "coming soon, don't miss it!!" message?  Then the
> > rest of the set could go through your tree without touching
> > driver-api/index.rst and, thus, avoiding the otherwise inevitable
> > conflicts?  
> 
> So just patch 1 still for 4.10 through your tree? Sounds good to me.

Yeah, that will work just fine, I'll slip it in.

Thanks,

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH 0/5] sphinxification for dma-buf docs

[Jonathan Corbet]

On Sun, 11 Dec 2016 13:35:49 +0100
Daniel Vetter  wrote:

> > It seems like just the sort of thing we want to be doing to pull the docs
> > together in a more rational way.  
> 
> Ok if we pull this in through gfx trees? Will miss 4.10 though, that's
> already finished and in bugfix-only mode.

I've pretty much closed up 4.10 as well.

Here's a thought, though: how about if we slip in a little version of
dma-buf.rst now with a "coming soon, don't miss it!!" message?  Then the
rest of the set could go through your tree without touching
driver-api/index.rst and, thus, avoiding the otherwise inevitable
conflicts?

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH 0/5] sphinxification for dma-buf docs

[Jonathan Corbet]

On Fri,  9 Dec 2016 19:53:04 +0100
Daniel Vetter  wrote:

> Not yet everything in this area, I still want to sprinkle nice docs around all
> the fence code. Especially some text to explain implicit vs. explicit fencing
> and how it's all supposed to work.
> 
> But just cleanup in the dma-buf part was quite a bit of work, and I'd like to
> get feedback on that before moving on.

No complaints here - except that I had to go looking around to find this
0/5 posting explaining what the overall goal was...:)

It seems like just the sort of thing we want to be doing to pull the docs
together in a more rational way.

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] linux-next: manual merge of the jc_docs tree with the drm-misc tree

[Jonathan Corbet]

On Fri, 19 Aug 2016 11:52:15 +1000
Stephen Rothwell  wrote:

> Today's linux-next merge of the jc_docs tree got a conflict in:
> 
>   Documentation/gpu/index.rst
> 
> between commit:
> 
>   b754b35b089d ("vgaarbiter: rst-ifiy and polish kerneldoc")
> 
> from the drm-misc tree and commit:
> 
>   505f711174b0 ("doc-rst: add index to sub-folders")
> 
> from the jc_docs tree.
> 
> I fixed it up (see below) and can carry the fix as necessary.

Thanks, the fix is good.

Daniel: my apologies, I should have asked for that patch to be split up
and the relevant pieces sent through the gpu and media trees.

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH 1/2] doc/sphinx: Enable keep_warnings

[Jonathan Corbet]

On Tue, 19 Jul 2016 13:42:54 +0200
Daniel Vetter  wrote:

> Unfortunately warnings generated after parsing in sphinx can end up
> with entirely bogus files and line numbers as sources. Strangely for
> outright errors this is not a problem. Trying to convert warnings to
> errors also doesn't fix it.
> 
> The only way to get useful output out of sphinx to be able to root
> cause the error seems to be enabling keep_warnings, which inserts
> a System Message into the actual output. Not pretty at all, but I
> don't really want to fix up core rst/sphinx code, and this gets the job
> done meanwhile.

I'll go ahead and apply this.  It *would* be nice, someday, to figure out
how to get proper info out for warnings directly, but until somebody gets
there...

Thanks,

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH 5/5] drm: Enable markdown^Wasciidoc for gpu.tmpl

[Jonathan Corbet]

On Thu, 14 Jan 2016 22:03:26 +0200
Jani Nikula  wrote:

> What if we added support for some markup language as an alternative to
> DocBook for the high level documentation? What if we taught kernel-doc
> to output said markup natively, and included those generated pieces into
> the high level documentation using the markup's own include directives?
> At least AsciiDoc and reStructuredText support this.

That is kind of what I've been thinking.  I think we could dispense with
docbook entirely, simplifying the toolchain and making the template files
easier to read and edit.  Something like that would also make it easy to
keep the regular .txt documents in a structured form and to integrate them
into the "formatted" documents if it makes sense.

Jani, want to join us at LCA and talk about it? :)

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH 5/5] drm: Enable markdown^Wasciidoc for gpu.tmpl

[Jonathan Corbet]

On Sat, 12 Dec 2015 12:13:45 +0100
Daniel Vetter  wrote:

> I just figured there's no way this could get it, and I'd
> much rather improve the docs themselves than trying to convince core
> kernel folks that this might be useful.

So I'm not quite sure why you figured that; I never said it, certainly.

I've been messing with it a bit, seems to work.  I do still wish we could
consider alternatives, especially those that might simplify the toolchain
rather than complicating it.  But it's clear that I'm not succeeding in
finding time to actually explore that idea; the contents of $EXCUSES are
good, but the end result is the same.  And the patch fairy just isn't
coming through for me on this one.

In my mind, there's clearly no good that can come from (further) delaying
something that works in favor of an "it would be nice" that may never
even exist.  So I'm currently thinking that I'll pull this into the docs
tree once the merge window is done, with the plan to push it for 4.6.
Then we can see if anybody screams.

That gives a couple of weeks for an updated patch set, should you have
one.

The build-time increase is painful in the extreme - about a factor of
three for a -j1 build, and that's with only one file using the feature.
It feels wrong, somehow, for the docs build to take longer than building
the kernel itself.  Can we do something about that?

 - How many of the comments actually use asciidoc features?  Might there
   be some possibility of detecting those in kernel-doc and skipping the
   callout to asciidoc when it's not needed?

 - Pandoc seems to do asciidoc.  I still don't like the idea of depending
   on it for this to work, but having the *option* to use it is fine.  If
   it's really that much faster (yes, Python startup is painful) then
   maybe providing the option is worth it.

 - All over the kernel we've seen that batching improves performance.  It
   would take a bit of work, but I bet kernel-doc could put together all
   the snippets from one file, pass them through a single asciidoc
   invocation, then split the results back apart.  That would probably
   eliminate the performance hit entirely.

None of that is a condition for pulling this stuff in, but can it be
looked into?

Thanks,

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH 5/5] drm: Enable markdown^Wasciidoc for gpu.tmpl

[Jonathan Corbet]

On Wed, 25 Nov 2015 18:07:59 +0100
Daniel Vetter  wrote:

> Unfortunately the entire improved docbook project died at KS in a
> massive bikeshed. So we need to carry this around in drm private trees
> forever :(

I don't think that's an entirely helpful way to look at things, honestly.
Changing how the docs system works affects a lot of people, they're going
to have input on the matter.

And I sure hope it hasn't "died".  The posting of these patches suggests
that perhaps it has not.

Anyway, I wanted to say that, my silence notwithstanding, I haven't just
dropped these.  I had some hassles to deal with (replacing the entire LWN
server infrastructure, for example) but those are done; I hope to be able
to mess with this stuff a bit in the very near future.

Have the table-rendering issues that Graham talked about before gotten any
better with the newer scheme?

Thanks,

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH v2 2/4] scripts/kernel-doc: Replacing highlights hash by an array

[Jonathan Corbet]

On Tue, 17 Nov 2015 08:40:46 -0200
Mauro Carvalho Chehab  wrote:

> The above causes some versions of perl to fail, as keys expect a
> hash argument:
> 
> Execution of .//scripts/kernel-doc aborted due to compilation errors.
> Type of arg 1 to keys must be hash (not private array) at 
> .//scripts/kernel-doc line 2714, near "@highlights) "
> 
> This is happening at linuxtv.org server, with runs perl version 5.10.1.

OK, that's not good.  But I'm not quite sure what to do about it.

Perl 5.10.1 is a little over six years old.  Nobody else has complained
(yet) about this problem.  So it might be best to "fix" this with a
minimum version added to the Changes file.

Or maybe we need to revert the patch.

So I'm far from a Perl expert, so I have no clue what the minimum version
would be if we were to say "5.10.1 is too old."  I don't suppose anybody
out there knows?

Thanks,

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH v2 2/4] scripts/kernel-doc: Replacing highlights hash by an array

[Jonathan Corbet]

On Tue, 17 Nov 2015 13:29:49 -0200
Mauro Carvalho Chehab  wrote:

> The enclosed patch should do the trick. I tested it with perl 5.10 and 
> perl 5.22 it worked fine with both versions.

Indeed it seems to work - thanks!  Applied to the docs tree, I'll get it
upstream before too long.

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [RFC] Docs: drm: Move KMS properties table out to source files

[Jonathan Corbet]

On Mon, 28 Sep 2015 10:36:59 +0100
Graham Whaley  wrote:

> I've still not thought of a way of tweaking the kernel-doc and pandoc
> processing to work around this either, as they are done as different
> passes/phases that neither has knowledge about the others
> requirements.
> 
> As it stands, I'm failing to find a method to break out the DRM table
> into markdown tables that I believe works, fundamentally due to this
> 'incompatibility' between the kernel-doc and pandoc_markdown processing
> phases around the highlight processing.

This sort of thing is why I'm increasingly nervous about this one-off mix
of doc-generation tools we're putting together.  Sigh.

One possibility might be to have kernel-doc understand some sort of table
notation of its own and make it do the right thing.

Another might be to have kernel-doc format unconditionally to markdown
(or ReST, or something) all the time, then have the secondary processor
handle everything from there.  A bigger change, obviously.  Probably not
something anybody wants to face, but we may reach a point where we need
to consider having less than three independent formatting tools in the
mix.  I *may* get a chance to mess with this idea in the next week or so,
but no promises.

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH 0/6] scripts/kernel-doc: Kernel-doc improvements

[Jonathan Corbet]

On Sun, 13 Sep 2015 12:36:07 +0200
Daniel Vetter  wrote:

> Personally I don't care which kind of text markup we pick and wich
> converter, as long as the project looks reasonable far away from
> immeninent death (way too many one-person projects on github in this
> area).
> 
> But if we have this discussion I'd like to decouple it from the other
> kerneldoc improvemnts in this series (patches 1, 5 and 6). If we cant
> agree on the text markup then drm docs will simply look a bit funny for
> everyone else. But if the inline struct stuff won't happen 0-day will
> scream around (and there's already patches which use the new layout).

Those patches are:

1)  scripts/kernel-doc: Replacing highlights hash by an array
5)  scripts/kernel-doc: Improve Markdown results
6)  scripts/kernel-doc: Processing -nofunc for functions only

#1 is fine, I'll merge that today.  #6 is already merged.  #5 is a markdown
patch, though, and doesn't make sense without the others?  Are you thinking
about #3 (drm/doc: Convert to markdown)?  That one would almost work (it
depends on #2 currently) and it nicely shows *why* I'd like to get away from
XML... 

> > 2 We're constructing an increasingly complicated document-processing
> >   mechanism with a lot of independently moving parts.  What if we
> >   converted the whole document to markdown and dispensed with the XML
> >   part altogether?  Making the source files simpler and dispensing with
> >   the xmlto requirement would be a big win, IMO.
> 
> Who's going to convert the almost 30kloc of xml template (which often have
> large amounts of texts) and the over 60k kerneldoc comments that we have
> already?

I thought you'd do that :)

Seriously, though, a change would be a big job.  There's a reason I've said
several times that it would make no sense to delay the work at hand in the
hopes of somebody doing this whole job instead.  But we can certainly
ponder what might be better.

Getting rid of the XML stuff may well simplify the whole process and make
the documentation much more accessible for those who would change it; that
could be a goal worth going for.  Oh, and anything requiring changes to the
kerneldoc comments is going nowhere, that was never something I'd
contemplated.  Those comments are fine.

But any such change needs a lot of thought and a reasonable proof of
concept.  Meanwhile we have work that can make the docs better now, and I
want to merge it.  But we should choose the tools we use carefully, and I
anticipate a lot of opposition to one that has to drag in 70 Haskell
packages with it.

> > I will not make #2 be a precondition to getting some form of this work
> > merged, but I would like to have a good answer for #1.  Adding such a
> > heavyweight dependency (even as an optional one) needs to have a pretty
> > good story behind it.
> 
> Should we discuss #1 at ks? Imo as long as no one pipes up to do the
> massive conversion away from the current toolchain (and subsystem
> maintainers won't just kill that effort because it causes too much churn)
> moving forward with the kerneldoc toolchain we have makes sense. Hence I'd
> like to see those patches landed before we resolve #1 if possible.

I've tossed the topic out there; the kernel summit agenda hasn't been made
yet, though.  In any case, I'd be happy to resolve this particular issue
before then if it were possible.

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH 1/6] scripts/kernel-doc: Replacing highlights hash by an array

[Jonathan Corbet]

On Mon,  7 Sep 2015 17:01:59 -0300
Danilo Cesar Lemes de Paula  wrote:

> 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:
>   - @device_for_each_child
> 
> 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.

OK, I've spent a bunch of time with this, comparing the results before
and after.  The output you mention is clearly wrong, but there might be
room to differ over what the root cause is.

That output is caused by @device_for_each_child() in the comments.  This
happens for a few other functions as well, and I think it's wrong.  @ is
used to indicate parameters (or structure fields); I'm not sure why
people are using it for functions that are *not* one of the above.
Formatting the function names as a parameter doesn't seem right either.

There is the occasional case where the parameter *is* a function and the
text uses the () notation (threadfn(), for example).  Having the
"parameter" style win out over the "function" style in such cases is OK,
I guess, but it would be good to format the parentheses along with the
name.  The function patterns there now drop the parentheses entirely,
which seems a bit strange to me.

I guess I'll apply the patch; determinism is good, and it doesn't make
anything screwy that wasn't already that way.  But I think we should fix
the misapplied @s and sort out function formatting in general.  One of
these days...

Thanks,

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH 0/6] scripts/kernel-doc: Kernel-doc improvements

[Jonathan Corbet]

On Mon,  7 Sep 2015 17:01:58 -0300
Danilo Cesar Lemes de Paula  wrote:

> The following series contains:
>  * kernel-doc: markdown support and improvements.

OK, I've spent a while looking this stuff over.  I like the general idea,
but I do have a couple of concerns.

1 Installing pandoc on a Fedora system wants to drag in 70(!) packages
  for 100MB of total stuff.  Installing it on Arch is ... well ... enough
  to make you want to switch to Fedora.  If we add a dependency on a tool
  this massive, people are going to complain, loudly.

  Have you looked at using something like cmark instead?  I don't know
  the tool well, but it seems like it can do the job simply enough.  It's
  focused, written in C, and doesn't drag in a diskful of Haskell
  stuff.  There's lot of other converters out there too, I'm not tied to
  this one (though I think CommonMark deserves support), but I do think
  this question needs to be considered.

2 We're constructing an increasingly complicated document-processing
  mechanism with a lot of independently moving parts.  What if we
  converted the whole document to markdown and dispensed with the XML
  part altogether?  Making the source files simpler and dispensing with
  the xmlto requirement would be a big win, IMO.

I will not make #2 be a precondition to getting some form of this work
merged, but I would like to have a good answer for #1.  Adding such a
heavyweight dependency (even as an optional one) needs to have a pretty
good story behind it.

Thanks,

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH] scripts/kernel-doc: Processing -nofunc for functions only

[Jonathan Corbet]

On Tue,  1 Sep 2015 14:44:14 -0300
Danilo Cesar Lemes de Paula  wrote:

> Docproc process 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 do not add them
> to the final documentation. This patch fixes it.
> 
> This is non-usual and 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.

I've verified that it indeed affects nothing else; it's in the docs tree
now, thanks.

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH] scripts/kernel-doc: Improve Markdown results

[Jonathan Corbet]

On Fri, 4 Sep 2015 14:53:34 -0300
Danilo Cesar Lemes de Paula  wrote:

> In the last few days I sent three features:
> Markdown support (patch series 1)
> Cross-reference hyperlink support (patch series 1)
> in-struct-body documentation (series 2)
> 
> I assume you want a new patch series for the series 1, containing the
> feature itself and the fixes that I sent later, correct?

The cross-reference patch was merged, so there's no need to send that
again.  Anything else that isn't in mainline now should be resent as a
new series.

Thanks,

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH] scripts/kernel-doc: Improve Markdown results

[Jonathan Corbet]

On Tue, 1 Sep 2015 14:57:33 -0300
Danilo Cesar Lemes de Paula  wrote:

> Did you find time to check this patch? As you mentioned that you applied
> the Markdown support for the linux-next tree, this patch might be needed
> (maybe "wanted" is a better word).

Not quite what I said...I said I'd apply it right after the merge window
so it can sit in linux-next through the full cycle.  It's a bit early to
be pushing 4.4 stuff into linux-next now...

Beyond that, I wasn't sure where things stand with fixes... Can you send
me a new patch set with this fix (and any others that might
exist) integrated in?

Thanks,

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH 0/4] Add support for Hyperlinks and Markup on kernel-doc

[Jonathan Corbet]

On Thu, 13 Aug 2015 20:09:35 -0300
Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk wrote:

 Did you find time to take a look on this?

No.  Just when I thought things couldn't get crazier, my laptop died.  

https://plus.google.com/+JonathanCorbet/posts/FBHp48dPb95

What spare time I had has been dedicated to recovering from that in time
to give my talk next week.
 
 I understand that there's some discussion behind the curtains regarding
 the markdown support, but the cross-reference-hyperlink patch is also in
 the same patch series. It doesn't change any text in the docbook unless
 there's really a cross-reference link to it. Different from the markdown
 support (when people start to use markdown to write docs it will be hard
 to go back), the cross-link stuff doesn't require/create any change to
 current documentation, it is pretty safe to use.
 
 Would you mind to share your plans about this?

No behind-the-curtains discussions happening, or, let's say, if there
are, I've not been invited either.

I'd like to get back to the cross-reference stuff.  Last I tried, it
failed while building the media docs; have you been able to look at
that?  

Longer term, as you may know from the kernel summit discussions, I'd
really like to get rid of a lot of the XML gunk and put in something more
straightforward, be it based on Markdown or something else.  Doing that,
however, requires that I find the time to implement something that's
convincingly better.  It may happen soon, but I sure can't guarantee it.

Meanwhile, I think it would be a horrible mistake to delay useful work
because I have a gleam in my eye to do something different one of these
years, so I'll not do that.  I fully expect to merge all of the stuff
you've done, I just need to have a good look at it and test it out a
bit.  As I said before, I can't promise that for the 4.3 merge window,
but I'll try.

Apologies,

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH v2] scripts/kernel-doc Allow struct arguments documentation in struct body

[Jonathan Corbet]

On Tue,  4 Aug 2015 09:04:08 -0300
Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk wrote:

 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.

OK, this change has been merged into the docs tree.

Thanks,

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH] scripts/kernel-doc Allow struct arguments documentation in struct body

[Jonathan Corbet]

On Mon, 3 Aug 2015 10:23:19 +0200
Daniel Vetter dan...@ffwll.ch wrote:

  I'm wondering if we need a kernel summit session on commenting
  conventions, markdown-in-kerneldoc, etc?  Maybe I'll stick a proposal out
  there.  
 
 Might be useful, but I'm not sure how many people really would actively
 work on improving the tooling. The only comment I've seen is to maybe use
 gtkdoc, but that would be a pain since it's slightly incompatible with
 kerneldoc.

The idea was to get a sense for what sort of improvements would be
useful, to begin with.  But my attempt to start a discussion on the
kernel summit list appears to have hit the ground pretty hard; I guess
that means I have free rein :)

I expect I'll apply the struct-args doc patch in the fairly near future.
Then we'll see if others complain when patches using it start to show up,
but the feature itself shouldn't break anything.  I'm *really* hoping to
take a hard look at Danilo's stuff for a 4.3 merge as well.  It should be
possible, but there's real-world obnoxiousness that is doing its best to
get in the way.

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH] scripts/kernel-doc Allow struct arguments documentation in struct body

[Jonathan Corbet]

On Fri, 31 Jul 2015 18:06:45 -0300
Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk wrote:

 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.

Interesting approach.  I think it could make sense, but I fear pushback
from a subset of maintainers refusing to accept this mode.  I wonder what
it would take to get a consensus on allowing these in-struct comments?

I'm wondering if we need a kernel summit session on commenting
conventions, markdown-in-kerneldoc, etc?  Maybe I'll stick a proposal out
there.

Thanks,

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH 0/4] Add support for Hyperlinks and Markup on kernel-doc

[Jonathan Corbet]

On Thu, 23 Jul 2015 15:16:23 -0300
Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk wrote:

 This series add supports for hyperlink cross-references on Docbooks and
 an optional markup syntax for in-source Documentation.

I like the idea; just be warned that it's likely to be a week or two and
one more ocean crossing before I can take a serious look at this...

Thanks,

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [Intel-gfx] [PATCH v2] scripts/kernel-doc: Adding cross-reference links to html documentation.

[Jonathan Corbet]

On Fri, 26 Jun 2015 12:08:57 -0300
Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk wrote:

 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.

So I put a lot more time into this today than I really had available.  I
think it's cool stuff, and we definitely want it.  But can I ask for one
more pass?  In particular:

 - It makes the docs build a lot more noisy, that would be nice to fix.

 - A bit more documentation in the script would be nice.  It also is happy
   to run with silly arguments; a detail since nobody will run it
   directly, but still...

 - Most importantly, it breaks make htmldocs; in particular, vast
   amounts of error spew results when it gets around to media_api.html.  I
   spent a while trying to figure out what was going on but didn't come up
   with anything conclusive; my suspicion is that it has to do with the
   separate makefile in Documentation/DocBook/media/.

Thanks,

jon
___
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx