Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST markup

[S. Fricke]

Hi Peter,

> On Fri, Nov 25, 2016 at 03:59:45PM +0100, Silvio Fricke wrote:
> > ... and move to core-api folder.
> > 
> > Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com>
> > ---
> >  Documentation/atomic_ops.txt => Documentation/core-api/atomic_ops.rst | 
> > 777 +---
> >  Documentation/core-api/index.rst  |   
> > 1 +-
> >  Documentation/process/volatile-considered-harmful.rst |   
> > 3 +-
> >  3 files changed, 404 insertions(+), 377 deletions(-)
> 
> Not a fan of this. The atomic_ops.txt file needs a lot of love, and I
> wouldn't want to edit a .rst file.

What is the problem with this rst-file? atomic_ops.rst are not so different to
the txt variant.


I will drop this patch.

Best regards,
Silvio


-- 
-- S. Fricke  sil...@port1024.net --
   Diplom-Informatiker (FH)
   Linux-Development Matrix: @silvio:port1024.net   

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 3/4] Documentation/local_ops.txt: convert to ReST markup

[S. Fricke]

test_exit);
> > -
> > -MODULE_LICENSE("GPL");
> > -MODULE_AUTHOR("Mathieu Desnoyers");
> > -MODULE_DESCRIPTION("Local Atomic Ops");
> >  END ---
> > +the ``local_t`` variable as a counter of bytes written in a buffer: there 
> > should
> > +be a ``smp_wmb()`` between the buffer write and the counter increment and 
> > also a
> > +``smp_rmb()`` between the counter read and the buffer read.
> > +
> > +
> > +Here is a sample module which implements a basic per cpu counter using
> > +``local.h``.
> > +
> > +.. code-block:: c
> 
> Better to use :: instead of code-block.
> 
> > +
> > +/* test-local.c
> > + *
> > + * Sample module for local.h usage.
> > + */
> > +
> > +
> > +#include 
> > +#include 
> > +#include 
> > +
> > +static DEFINE_PER_CPU(local_t, counters) = LOCAL_INIT(0);
> > +
> > +static struct timer_list test_timer;
> > +
> > +/* IPI called on each CPU. */
> > +static void test_each(void *info)
> > +{
> > +/* Increment the counter from a non preemptible context */
> > +printk("Increment on cpu %d\n", smp_processor_id());
> > +local_inc(this_cpu_ptr());
> > +
> > +/* This is what incrementing the variable would look like 
> > within a
> > + * preemptible context (it disables preemption) :
> > + *
> > + * local_inc(_cpu_var(counters));
> > + * put_cpu_var(counters);
> > + */
> > +}
> > +
> > +static void do_test_timer(unsigned long data)
> > +{
> > +int cpu;
> > +
> > +/* Increment the counters */
> > +on_each_cpu(test_each, NULL, 1);
> > +/* Read all the counters */
> > +printk("Counters read from CPU %d\n", smp_processor_id());
> > +for_each_online_cpu(cpu) {
> > +printk("Read : CPU %d, count %ld\n", cpu,
> > +local_read(_cpu(counters, cpu)));
> > +}
> > +del_timer(_timer);
> > +test_timer.expires = jiffies + 1000;
> > +add_timer(_timer);
> > +}
> > +
> > +static int __init test_init(void)
> > +{
> > +/* initialize the timer that will increment the counter */
> > +init_timer(_timer);
> > +test_timer.function = do_test_timer;
> > +test_timer.expires = jiffies + 1;
> > +add_timer(_timer);
> > +
> > +return 0;
> > +}
> > +
> > +static void __exit test_exit(void)
> > +{
> > +del_timer_sync(_timer);
> > +}
> > +
> > +module_init(test_init);
> > +module_exit(test_exit);
> > +
> > +MODULE_LICENSE("GPL");
> > +MODULE_AUTHOR("Mathieu Desnoyers");
> > +MODULE_DESCRIPTION("Local Atomic Ops");
> 
> 
> 
> Thanks,
> Mauro

-- 
-- S. Fricke  sil...@port1024.net --
   Diplom-Informatiker (FH)
   Linux-Development Matrix: @silvio:port1024.net   

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 4/4] Documentation/workqueue.txt: convert to ReST markup

[S. Fricke]

Hi Silvio,

> [...]
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 28a1ff6..7e1efa2 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -19,6 +19,7 @@ Contents:
> media/index
> gpu/index
> 80211/index
> +   misc/index

The needs to be removed too.

>  
>  Indices and tables
>  ======
> [...]


Sorry,
Silvio

-- 
-- S. Fricke  sil...@port1024.net --
   Diplom-Informatiker (FH)
   Linux-Entwicklung JABBER: sil...@conversation.port1024.net   

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 3/3] Documentation/workqueue.txt: convert to ReST markup

[S. Fricke]

Hi Jon,

> On Wed, 19 Oct 2016 20:38:39 +0200
> Silvio Fricke <silvio.fri...@gmail.com> wrote:
> 
> > This patch add a "misc" documentation section and add the workqueue
> 
> Thanks for doing this; can I add a few comments?
> 
> - Ccing the docs maintainer is considered good form with documentation
>   patches :)  That's especially true of anything touching index.rst, which
>   has become a bit of a conflict point.
> 
> - On a quick read, the conversion of workqueue.txt seems good.
> 
> - I don't like the "misc" thing, though.
> 
> As we convert the documentation over, we want to impose a bit more
> organization on it, both in the documentation structure and in the
> filesystem structure.  That means moving a lot of the stuff out of the
> top-level Documentation/ directory, which is an unmanageable mess at the
> moment.  So one thing I would really rather not see is people creating
> index.rst files with "../" in them.  The file hierarchy should match the
> document hierarchy.
> 
> For 4.9 we created the driver-api manual for stuff that's clearly
> driver-specific.  My thinking had been to make a core-api equivalent for
> stuff that's relevant outside of the driver code; workqueue.txt clearly
> qualifies there.
> 
> So I guess what I'd like to see is something very similar to what you've
> done, but can we start the core-api manual, and put the RST file as
> core-api/workqueue.rst?  The core-api manual itself doesn't really need to
> be any more than what you did for misc/ at this point.

Thanks for your hints, I will update my patchset.  


Best regards,
Silvio

> That done, if it's OK with you, Tejun, I'd prefer to take it through the
> docs tree with your ack so I don't have to write yet another note to Linus
> explaining the index.rst conflicts...
> 
> Sound OK?
> 
> Thanks,
> 
> jon

-- 
-- S. Fricke  sil...@port1024.net --
   Diplom-Informatiker (FH)
   Linux-Entwicklung JABBER: sil...@conversation.port1024.net   

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH 1/3] kernel-doc: better parsing of named variable arguments

[S. Fricke]

Hi Jani,

thanks for your review.

> On Sun, 16 Oct 2016, Silvio Fricke  wrote:
> > Without this patch we get warnings for named variable arguments.
> >
> > warning: No description found for parameter '...'
> > warning: Excess function parameter 'args' description in 
> > 'alloc_ordered_workqueue'
> >
> > Signed-off-by: Silvio Fricke 
> > ---
> >  scripts/kernel-doc |  9 +++--
> >  1 file changed, 7 insertions(+), 2 deletions(-)
> >
> > diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> > index 93721f3..cd5d830 100755
> > --- a/scripts/kernel-doc
> > +++ b/scripts/kernel-doc
> > @@ -211,7 +211,7 @@ my $anon_struct_union = 0;
> >  # match expressions used to find embedded type information
> >  my $type_constant = '\%([-_\w]+)';
> >  my $type_func = '(\w+)\(\)';
> > -my $type_param = '\@(\w+)';
> > +my $type_param = '\@(\w+\.{0,3})';
> 
> You need to be careful with this one, as it also impacts highlights in
> text. That should be 0 or 3 dots, not 0, 1, 2 or 3 dots, at the
> end. Otherwise a sentence ending in a "see @foo." would end up
> highlighting the single dot too.

Good point, thanks.
My first attempt was a regexp like this one '\@(\w+(?:\.\.\.)?)'. But I got
several errors like:

Sequence (? incomplete in regex; marked by <-- HERE in m/\@(\w+(? <-- HERE
/ at (eval 1) line 11,  line 146.

I have switched the inner non-cap group to a capture group via
'\@(\w+(\.\.\.)?)' and it works, but Is this wrong?

Best regards,
Silvio

> 
> >  my $type_fp_param = '\@(\w+)\(\)';  # Special RST handling for func ptr 
> > params
> >  my $type_struct = '\&((struct\s*)*[_\w]+)';
> >  my $type_struct_xml = '\\((struct\s*)*[_\w]+)';
> > @@ -2353,7 +2353,12 @@ sub push_parameter($$$) {
> >  
> > if ($type eq "" && $param =~ /\.\.\.$/)
> > {
> > -   $param = "...";
> > +   if ($param =~ /\w\.\.\.$/) {
> > + # handles ARGNAME... parameter
> > + $param = $param;
> 
> What's the point? Why not just check if param does not match?
> 
> BR,
> Jani.
> 
> 
> > +   } else {
> > + $param = "...";
> > +   }
> > if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq 
> > "") {
> > $parameterdescs{$param} = "variable arguments";
> > }
> 
> -- 
> Jani Nikula, Intel Open Source Technology Center

-- 
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html