Deprecate doc attribute?

[cdce8p]

With the new addition of doc_node (#1276), should the "old" doc attribute be deprecated and later removed?

/CC: @DanielNoord

[DanielNoord]

Yeah, I don't see a reason to keep it. It only adds unnecessary overhead and attributes. I'm +1.

Do we want to deprecate in 2.11 as well?

[cdce8p]

Do we want to deprecate in 2.11 as well?

It would make sense IMO 🤔 Need to see if I have the time to work on a PR later today.

[DanielNoord]

@cdce8p If you want I can make a PR for this so you only have to review. That should take you less time (depending on the quality of my PR 😄)

[cdce8p]

@cdce8p If you want I can make a PR for this so you only have to review. That should take you less time (depending on the quality of my PR 😄)

Go for it! I did start working on it but haven't had the time to finish it. You're welcome to use my changes if you find them useful. Just know that there might still be some bugs. main...cdce8p:deprecate-doc

[DanielNoord]

Copied from #1432 (review):

What I have mind

• Update Module, ClassDef, FunctionDef.
  1.1 The doc attribute in __init__ should be optional with default. Required if we later want to remove it from existing calls.
  1.2 Property and property setter method for doc with DeprecationWarning
  -> Deprecate accessing the doc attribute on nodes #1434
• Update other (similar) classes, mainly object.Property and PartialFunction, with similar changes if necessary.
  -> Pass doc_node to postinit of all Property constructors #1436
  -> Pass doc_node to postinit of all PartialFunction constructors #1437
• Update code base, to remove the doc attribute where it's passed to __init__ and replace it with doc_node to postinit. Also update functions which could handle an optional doc_node instead of a string -> AsStringVisitor.
  -> No longer pass doc to various node constructors #1451
  -> Do no pass doc attribute to nodes.Module in tests #1455
  -> Deprecate passing doc to PartialFunction #1456
  -> Deprecate passing doc to Property #1457
  -> Do no pass doc attribute to nodes.ClassDef in tests #1458
• Deprecate passing the doc argument #1453
• ... Did I miss something 🤔 ... probably. Edit: by @DanielNoord I think not 😄
• Update all attribute calls to .doc if not already done. ClassModel.attr___doc__, AsStringVisitor._docs_dedent, ...
  -> Do not use doc attribute internally #1433
  -> Make _docs_dedent use doc_node #1448

[DanielNoord]

@Pierre-Sassoulas I think the work on doc is nearing its conclusion.

Perhaps we can get #1450 in 2.11 as well, but I suggest moving all other issues to the 2.12 milestone. None of the open issues are particularly pressing for pylint and the release of astroid kind of is.

[DanielNoord]

WIth https://github.com/PyCQA/astroid/runs/5486844569?check_suite_focus=true passing on main without any DeprecationWarnings for doc being raised I guess the work here is done 😄

[cdce8p]

Thanks for the help @DanielNoord 🚀