Re: [PATCH 12/12] docs: kdoc: Improve the output text accumulation

[Mauro Carvalho Chehab]

Em Fri, 11 Jul 2025 06:49:26 -0600
Jonathan Corbet <corbet@xxxxxxx> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> writes:
> 
> > Em Thu, 10 Jul 2025 17:30:20 -0600
> > Jonathan Corbet <corbet@xxxxxxx> escreveu:
> >  
> >> Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> writes:
> >>   
> >> > With that, I would just drop this patch, as the performance is
> >> > almost identical, and using "emit()" instead of "+=" IMO makes
> >> > the code less clear.    
> >> 
> >> I've dropped the patch - for now - but I really disagree with the latter
> >> part of that sentence.  It is far better, IMO, to encapsulate the
> >> construction of our output rather than spreading vast numbers of direct
> >> string concatenations throughout the code.  So this one will likely be
> >> back in a different form :)  
> >
> > The main concern was related to performance penalty - as based on
> > the latest test results, Pyhon currently handles very poorly list
> > concat (30% to 200% slower at the latest test results).  
> 
> Yes, I understood that part
> 
> > Yet, at least for me with my C-trained brain parsing, I find "=+" a
> > lot easier to understand than some_function().
> >
> > Btw, IMHO Python is not particularly great with names for concat/accumulate
> > commands. For list, it is append(), for set it is add(). Yet, "+=" is almost
> > universal (from standard types, only sets don't accept it, using, 
> > instead, "|=", which kind of makes sense).
> >
> > Adding a function naming emit() - at least for me - requires an extra brain 
> > processing time to remember that emit is actually a function that doesn't
> > produce any emission: it just stores data for a future output - that may 
> > even not happen if one calls the script with "--none".  
> 
> OK, I'll ponder on a different name :)

I'm fine with that.

> Perhaps the new not_emit() could even be aware of --none and just drop
> the data on the floor.

The code already does that on a much more optimized way. This
is actually one of the improvements over the Perl version: we
don't need to implement anything special for none.

When --none is passed, the code sets out_style = OutputFormat(), 
which is pretty much an abstract class that doesn't do any output 
at all, and from where the ManOutput and Restformat classes
are inherited.

It only does two things:

- Applying filters, in order to filter-out warnings from things
  according with --import/--internal/--function arguments;

- print warnings for symbols after filtering them, with:

    def out_warnings(self, args):
        """
        Output warnings for identifiers that will be displayed.
        """

        warnings = args.get('warnings', [])

        for log_msg in warnings:
            self.config.warning(log_msg)

So, there's no emit()/no_emit()/print()... there. All output
types do nothing:

    # Virtual methods to be overridden by inherited classes
    # At the base class, those do nothing.
    def out_doc(self, fname, name, args):
        """Outputs a DOC block"""

    def out_function(self, fname, name, args):
        """Outputs a function"""

    def out_enum(self, fname, name, args):
        """Outputs an enum"""

    def out_typedef(self, fname, name, args):
        """Outputs a typedef"""

    def out_struct(self, fname, name, args):
        """Outputs a struct"""

Regards,
Mauro