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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Thu, 10 Jul 2025 08:41:19 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:

> Em Wed,  2 Jul 2025 16:35:24 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
> 
> > Building strings with repeated concatenation is somewhat inefficient in
> > Python; it is better to make a list and glom them all together at the end.
> > Add a small set of methods to the OutputFormat superclass to manage the
> > output string, and use them throughout.
> > 
> > Signed-off-by: Jonathan Corbet <corbet@lwn.net>  
> 
> The patch looks good to me. Just a minor nit below.
> 
> > ---
> >  scripts/lib/kdoc/kdoc_output.py | 185 +++++++++++++++++---------------
> >  1 file changed, 98 insertions(+), 87 deletions(-)
> > 
> > diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output.py
> > index ea8914537ba0..d4aabdaa9c51 100644
> > --- a/scripts/lib/kdoc/kdoc_output.py
> > +++ b/scripts/lib/kdoc/kdoc_output.py
> > @@ -73,7 +73,19 @@ class OutputFormat:
> >          self.config = None
> >          self.no_doc_sections = False
> >  
> > -        self.data = ""
> > +    #
> > +    # Accumulation and management of the output text.
> > +    #
> > +    def reset_output(self):
> > +        self._output = []
> > +
> > +    def emit(self, text):
> > +        """Add a string to out output text"""
> > +        self._output.append(text)
> > +
> > +    def output(self):
> > +        """Obtain the accumulated output text"""
> > +        return ''.join(self._output)  
> 
> I would prefer to use a more Pythonic name for this function:
> 
> 	def __str__(self)
> 
> This way, all it takes to get the final string is to use str():
> 
> 	out_str = str(out)
> 
> With that:
> 
> Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>


Hmm... actually, I would code it on a different way, using something like:

class OutputString:
    def __init__(self):
	"""Initialize internal list"""
        self._output = []
    
    # Probably not needed - The code can simply do, instead:
    # a = OutputString() to create a new string.
    def reset(self):
        """Reset the output text"""
        self._output = []
    
    def __add__(self, text):
	"""Add a string to out output text"""
        if not isinstance(text, str):
            raise TypeError("Can only append strings")
        self._output.append(text)
        return self

    def __str__(self):
        return ''.join(self._output)
    
    # and, if needed, add a getter/setter:

    @property
    def data(self):
        """Getter for the current output"""
        return ''.join(self._output)

    @data.setter
    def data(self, new_value):
        if isinstance(new_value, str):
	    self._output = [new_value]
	elif isinstance(new_value, list):
            self._output = new_value
        else:
            raise TypeError("Value should be either list or string")

That would allow things like:

	out = OutputString()
	out = out + "Foo" + " " + "Bar"
	print(out)

	out = OutputString()
	out += "Foo"
	out += " "
	out += "Bar"
	return(str(out))

and won't require much changes at the output logic, and IMO will
provide a cleaner code.

Thanks,
Mauro