I'm in general not a huge fan of documenting for the sake of documenting, so I'd be in agreement of not enforcing it via code but rather be enforced by the reviewers in cases they believe certain methods need documenting.
-- Regards, Aritra Basu On Wed, Mar 20, 2024, 9:39 AM Jarek Potiuk <ja...@potiuk.com> wrote: > 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. >
