2

Suppose I have:

@dataclass(match_args = True)
class Foo:
  # a ton of attributes
  ...
  def update(self, **kwargs):
      """Update the Foo.

      Keyword Args:
       (a ton of text)
      """
      for arg in self.__match_args__:
        if arg in kwargs:
          self.__dict__[arg] = kwargs[arg]


class Bar:
  cfg = Foo()
  
  def set_cfg(self, **kwargs):
    """Set the cfg. 
    
    Keyword Args:
      see Foo.update
    """
    self.cfg.update(**kwargs)

What is the defensible (or proper) way to back-reference Foo's kwargs documentation, so that I can have 100% documentation but avoid copy pasting?

Preferably, it is in a way the IDE will maintain when I refactor. But if it isn't, that is cool too.

Chris
  • 28,822
  • 27
  • 83
  • 158
  • 2
    What's wrong with what you've done? I don't think there's anything that will copy the doc automatically. – Barmar Oct 12 '22 at 21:49
  • FYI, the source code for `json.dump` and `json.dumps`, which take the same keyword arguments, is a copy/paste. See https://github.com/python/cpython/blob/main/Lib/json/__init__.py#L120 – Barmar Oct 12 '22 at 21:53
  • But the web page documentation for `json.dumps()` just says "The arguments have the same meaning as in dump()." – Barmar Oct 12 '22 at 21:54
  • @Barmar oh I mean't if I change the name of "Foo" or "update" (although I am sure that will work). But if I refactor-move Foo, I could see how it might not be tracked properly by the IDE. – Chris Oct 12 '22 at 22:00
  • I see what you mean. I'm not sure there's a clean solution. – Barmar Oct 12 '22 at 22:04

0 Answers0