Re: [tip:perf/core] perf tools: Improve call graph documents and help messages

[Ingo Molnar <mingo@kernel.org>]

* Namhyung Kim <namhyung@kernel.org> wrote:

> Hi Ingo,
> 
> On Fri, Oct 23, 2015 at 6:03 PM, Ingo Molnar <mingo@kernel.org> wrote:
> >
> > * tip-bot for Namhyung Kim <tipbot@zytor.com> wrote:
> >
> >> Commit-ID:  76a26549eb367f683fbb394b7246bef5dc665f8c
> >> Gitweb:     http://git.kernel.org/tip/76a26549eb367f683fbb394b7246bef5dc665f8c
> >> Author:     Namhyung Kim <namhyung@kernel.org>
> >> AuthorDate: Thu, 22 Oct 2015 23:28:32 +0900
> >> Committer:  Arnaldo Carvalho de Melo <acme@redhat.com>
> >> CommitDate: Thu, 22 Oct 2015 16:23:19 -0300
> >>
> >> perf tools: Improve call graph documents and help messages
> >>
> >> The --call-graph option is complex so we should provide better guide for
> >> users.  Also change help message to be consistent with config option
> >> names.  Now perf top will show help like below:
> >>
> >>   $ perf top --call-graph
> >>     Error: option `call-graph' requires a value
> >>
> >>    Usage: perf top [<options>]
> >>
> >>       --call-graph <record_mode[,record_size],print_type,threshold[,print_limit],order,sort_key[,branch]>
> >>            setup and enables call-graph (stack chain/backtrace):
> >>
> >>               record_mode:    call graph recording mode (fp|dwarf|lbr)
> >>               record_size:    if record_mode is 'dwarf', max size of stack recording (<bytes>)
> >>                               default: 8192 (bytes)
> >>               print_type:     call graph printing style (graph|flat|fractal|none)
> >>               threshold:      minimum call graph inclusion threshold (<percent>)
> >>               print_limit:    maximum number of call graph entry (<number>)
> >>               order:          call graph order (caller|callee)
> >>               sort_key:       call graph sort key (function|address)
> >>               branch:         include last branch info to call graph (branch)
> >
> > Btw., how is the last line to be interpreted? Is the 'branch' value 0/1? If yes
> > then the text should probably say so? Or does the string 'branch' have to be used?
> 
> Yep, the string 'branch' should be used.

Yeah, so that wasn't very obvious, as there's a mixture of literal symbols with 
parameter names. For example:

       --call-graph <record_mode[,record_size],print_type,threshold[,print_limit],order,sort_key[,branch]>
            setup and enables call-graph (stack chain/backtrace):

so 'record_size' is obviously never to be written in a literal fashion - but 
'branch' is?

But I cannot think of a better solution, other than replacing:

                              default: 8192 (bytes)

with :
                              default: 8192 bytes

because in all other cases parantheses denote a specification of valid parameter 
values.

Thanks,

	Ingo