Re: [PATCH v3] perf tools: Document --children option in more detail

[Arnaldo Carvalho de Melo <acme@kernel.org>]

Em Wed, Apr 22, 2015 at 01:16:29AM +0900, Namhyung Kim escreveu:
> On Tue, Apr 21, 2015 at 12:41:33PM -0300, Arnaldo Carvalho de Melo wrote:
> > > +++ b/tools/perf/Documentation/overhead-calculation.txt
> > I think Ingo suggested that you renamed this file to include the word
> > "callchain" in it, no? looking at "overhead-calculation" I feel like I
> > first have to open it to figure out what kind of overhead is this,
> > perhaps it would be better named:

> > 	tools/perf/Documentation/callchain-overhead.txt
> > ?
 
> Please see my reply to the Ingo's post.  I think he agreed on this name.

I still find it confusing for the file name, where there is no context,
from just the file name when one does a 'ls tools/perf/Documentatoin' to
figure out about what overhead that is referring to.

So, perhaps a longer name:

tools/perf/Documentation/callchain-overhead-calculation.txt

?

Inside perf-{record,top}.txt, yeah, we have context, we know that this
is about post processing, formatting, etc.

<SNIP>
 
> > > +--no-children option on the command line or by adding 'report.children
> > > += false' or 'top.children = false' in the perf config file.
> > 
> > One can as well use the OPTION_FOO shortening mechanism and instead use:
> > 
> >      perf report --no-ch
> > 
> > Which is enough to disambiguate it from "--no-column-widths" and "--no-cpu".
> 
> Are you saying that you want to add the short form instead of the full
> --no-chlidren name?  I think we need to verbose in the manpage at
> least and it might not work in the future if some --chxxx option is
> added.

Perhaps:

"--no-children option on the command line or by adding 'report.children = false'
or 'top.children = false' in the perf config file.

A shorter form on the command line can be used, for instance '--no-ch'
is unambiguous at the time of this writing."
 
> > > diff --git a/tools/perf/Documentation/perf-report.txt b/tools/perf/Documentation/perf-report.txt
> > > index 4879cf638824..b7bb298deee3 100644
> > > --- a/tools/perf/Documentation/perf-report.txt
> > > +++ b/tools/perf/Documentation/perf-report.txt
> > > @@ -193,6 +193,7 @@ OPTIONS
> > >  	Accumulate callchain of children to parent entry so that then can
> > >  	show up in the output.  The output will have a new "Children" column
> > >  	and will be sorted on the data.  It requires callchains are recorded.
> > > +	See the `overhead calculation' section for more details.
> > 
> >                 `callchain overhead'
> 
> Do you prefer this name to 'overhead calculation'?  For me, it looks

It is ok with me "overhead calculation", as mentioned previously in this
message, the context in this perf-report.txt file should make it clear
that the overhead is about callchains.

> like saying about how much overhead will be added if we enabled
> callchains at perf record time or processing them at perf report time.

Ok.

- Arnaldo