Hey here, I wanted to quickly poll what people think about applying the https://docs.astral.sh/ruff/rules/undocumented-magic-method/ rule in our codebase. There are many uncontroversial rules - but that one is somewhat more controversial than others.
See https://github.com/apache/airflow/pull/37602#issuecomment-2001951402 and https://github.com/apache/airflow/pull/38277#pullrequestreview-1945745542 for example I think that even in the ruff example, but also in many cases requiring to document the methods will lead to rather useless documentation: class Cat(Animal): def __str__(self) -> str: """Return a string representation of the cat.""" return f"Cat: {self.name}" There is IMHO very little value in having such documentation. It might be useful in some cases where we have a really good reason to add such a magic method and it is important to document it, but in many cases - the documentation will be just documenting what the magic method already explains well (like the case above). This actually reminds me the early days of java documentation where javadoc looks more or less like this: "Paints the object" func paint() "Repaints the object" fund repaint() However - maybe I am wrong :). Maybe it's worth documenting those methods in bulk, even if in many cases it will not bring much value? WDYT ? Should we mandate documenting it - or leave up to the author to document it in case it feels like it is needed? J.
