[Chapel Merge] Adjust documentation for deprecated symbols

Branch: refs/heads/main
Revision: 4137c72
Author: lydia-duncan
Log Message:

Merge pull request #18397 from lydia-duncan/generateDeprecationDocs

Adjust documentation for deprecated symbols
[reviewed by @dlongnecke-cray]

When a symbol is deprecated, we generally want readers of the
documentation to know before they try to use that symbol. Instead
of forcing developers to write a warning for users of the deprecated
symbol by hand, have chpldoc check the documentation of the
symbol for any mention of deprecation (to avoid unnecessary extra
warnings) and if it isn't mentioned already add a warning about the
symbol being deprecated.

This change adds a new method to BaseAST, similar to the method
for printing the documentation field. This method is called from the
printDocs methods that actually print the documentation field.

Resolves #17948

Adds a test for:

  • classes
  • variables
  • modules
  • enums
  • functions
  • opaque extern type declarations

Based on the implementation, records, constants, configs, type declarations,
params, consts, and iterators should be handled by these adjustments.

  • [x] full paratest with futures

  • [x] make docs changed for all currently deprecated symbols

    Modified Files:
    A test/chpldoc/classes/deprecatedClasses.doc.catfiles
    A test/chpldoc/classes/deprecatedClasses.doc.chpl
    A test/chpldoc/classes/deprecatedClasses.doc.good
    A test/chpldoc/deprecatedSymbols.doc.catfiles
    A test/chpldoc/deprecatedSymbols.doc.chpl
    A test/chpldoc/deprecatedSymbols.doc.good
    A test/chpldoc/enum/deprecatedEnum.doc.catfiles
    A test/chpldoc/enum/deprecatedEnum.doc.chpl
    A test/chpldoc/enum/deprecatedEnum.doc.good
    A test/chpldoc/functions/deprecatedFunctions.doc.catfiles
    A test/chpldoc/functions/deprecatedFunctions.doc.chpl
    A test/chpldoc/functions/deprecatedFunctions.doc.good
    A test/chpldoc/globals/deprecateExternTypeVars.doc.catfiles
    A test/chpldoc/globals/deprecateExternTypeVars.doc.chpl
    A test/chpldoc/globals/deprecateExternTypeVars.doc.good
    A test/chpldoc/module/deprecatedModules.doc.catfiles
    A test/chpldoc/module/deprecatedModules.doc.chpl
    A test/chpldoc/module/deprecatedModules.doc.good
    M compiler/AST/AggregateType.cpp
    M compiler/AST/FnSymbol.cpp
    M compiler/AST/ModuleSymbol.cpp
    M compiler/AST/baseAST.cpp
    M compiler/AST/symbol.cpp
    M compiler/AST/type.cpp
    M compiler/include/baseAST.h

    Compare: https://github.com/chapel-lang/chapel/compare/be5adc1bcb62...4137c72ef7f1