From 10aba575facba48b2e49fef2af8266afd9e1555d Mon Sep 17 00:00:00 2001 From: Andreas Dangel Date: Mon, 11 Mar 2024 18:18:57 +0100 Subject: [PATCH] [doc] Review links in release notes - fix javadoc links --- docs/pages/release_notes_pmd7.md | 287 ++++++++++++++++--------------- 1 file changed, 146 insertions(+), 141 deletions(-) diff --git a/docs/pages/release_notes_pmd7.md b/docs/pages/release_notes_pmd7.md index af8ec352b7..e645ccff25 100644 --- a/docs/pages/release_notes_pmd7.md +++ b/docs/pages/release_notes_pmd7.md @@ -2599,8 +2599,8 @@ Please look at {% jdoc_package_old vm::lang.vm.ast %} to find out the full list **PLSQL AST** -The production and node `ASTCursorBody` was unnecessary, not used and has been removed. Cursors have been already -parsed as `ASTCursorSpecification`. +The production and node {% jdoc_old plsql::lang.plsql.ast.ASTCursorBody %} was unnecessary, not used and has been removed. Cursors have been already +parsed as {% jdoc plsql::lang.plsql.ast.ASTCursorSpecification %}. #### 6.21.0 @@ -2611,31 +2611,31 @@ parsed as `ASTCursorSpecification`. Those APIs are not intended to be used by clients, and will be hidden or removed with PMD 7.0.0. You can identify them with the `@InternalApi` annotation. You'll also get a deprecation warning. -* {% jdoc java::lang.java.JavaLanguageHandler %} -* {% jdoc java::lang.java.JavaLanguageParser %} -* {% jdoc java::lang.java.JavaDataFlowHandler %} -* Implementations of {% jdoc core::lang.rule.RuleViolationFactory %} in each - language module, eg {% jdoc java::lang.java.rule.JavaRuleViolationFactory %}. - See javadoc of {% jdoc core::lang.rule.RuleViolationFactory %}. -* Implementations of {% jdoc core::RuleViolation %} in each language module, - eg {% jdoc java::lang.java.rule.JavaRuleViolation %}. See javadoc of - {% jdoc core::RuleViolation %}. +* {% jdoc_old java::lang.java.JavaLanguageHandler %} +* {% jdoc_old java::lang.java.JavaLanguageParser %} +* {% jdoc_old java::lang.java.JavaDataFlowHandler %} +* Implementations of {% jdoc_old core::lang.rule.RuleViolationFactory %} in each + language module, eg {% jdoc_old java::lang.java.rule.JavaRuleViolationFactory %}. + See javadoc of {% jdoc_old core::lang.rule.RuleViolationFactory %}. +* Implementations of {% jdoc_old core::RuleViolation %} in each language module, + eg {% jdoc_old java::lang.java.rule.JavaRuleViolation %}. See javadoc of + {% jdoc_old core::RuleViolation %}. -* {% jdoc core::rules.RuleFactory %} -* {% jdoc core::rules.RuleBuilder %} -* Constructors of {% jdoc core::RuleSetFactory %}, use factory methods from {% jdoc core::RulesetsFactoryUtils %} instead -* {% jdoc core::RulesetsFactoryUtils#getRulesetFactory(core::PMDConfiguration, core::util.ResourceLoader) %} +* {% jdoc_old core::rules.RuleFactory %} +* {% jdoc_old core::rules.RuleBuilder %} +* Constructors of {% jdoc_old core::RuleSetFactory %}, use factory methods from {% jdoc_old core::RulesetsFactoryUtils %} instead +* {% jdoc_old core::RulesetsFactoryUtils#getRulesetFactory(core::PMDConfiguration, core::util.ResourceLoader) %} -* {% jdoc apex::lang.apex.ast.AbstractApexNode %} -* {% jdoc apex::lang.apex.ast.AbstractApexNodeBase %}, and the related `visit` - methods on {% jdoc apex::lang.apex.ast.ApexParserVisitor %} and its implementations. - Use {% jdoc apex::lang.apex.ast.ApexNode %} instead, now considers comments too. +* {% jdoc_old apex::lang.apex.ast.AbstractApexNode %} +* {% jdoc_old apex::lang.apex.ast.AbstractApexNodeBase %}, and the related `visit` + methods on {% jdoc_old apex::lang.apex.ast.ApexParserVisitor %} and its implementations. + Use {% jdoc_old apex::lang.apex.ast.ApexNode %} instead, now considers comments too. -* {% jdoc core::lang.ast.CharStream %}, {% jdoc core::lang.ast.JavaCharStream %}, - {% jdoc core::lang.ast.SimpleCharStream %}: these are APIs used by our JavaCC +* {% jdoc_old core::lang.ast.CharStream %}, {% jdoc_old core::lang.ast.JavaCharStream %}, + {% jdoc_old core::lang.ast.SimpleCharStream %}: these are APIs used by our JavaCC implementations and that will be moved/refactored for PMD 7.0.0. They should not be used, extended or implemented directly. -* All classes generated by JavaCC, eg {% jdoc java::lang.java.ast.JJTJavaParserState %}. +* All classes generated by JavaCC, eg {% jdoc_old java::lang.java.ast.JJTJavaParserState %}. This includes token classes, which will be replaced with a single implementation, and subclasses of {% jdoc core::lang.ast.ParseException %}, whose usages will be replaced by just that superclass. @@ -2644,34 +2644,34 @@ You can identify them with the `@InternalApi` annotation. You'll also get a depr * pmd-core * Many methods on the {% jdoc core::lang.ast.Node %} interface - and {% jdoc core::lang.ast.AbstractNode %} base class. See their javadoc for details. - * {% jdoc !!core::lang.ast.Node#isFindBoundary() %} is deprecated for XPath queries. + and {% jdoc_old core::lang.ast.AbstractNode %} base class. See their javadoc for details. + * {% jdoc_old !!core::lang.ast.Node#isFindBoundary() %} is deprecated for XPath queries. * pmd-java - * {% jdoc java::lang.java.AbstractJavaParser %} - * {% jdoc java::lang.java.AbstractJavaHandler %} + * {% jdoc_old java::lang.java.AbstractJavaParser %} + * {% jdoc_old java::lang.java.AbstractJavaHandler %} * [`ASTAnyTypeDeclaration.TypeKind`](https://javadoc.io/page/net.sourceforge.pmd/pmd-java/6.21.0/net/sourceforge/pmd/lang/java/ast/ASTAnyTypeDeclaration.TypeKind.html) - * {% jdoc !!java::lang.java.ast.ASTAnyTypeDeclaration#getKind() %} - * {% jdoc java::lang.java.ast.JavaQualifiedName %} - * {% jdoc !!java::lang.java.ast.ASTCatchStatement#getBlock() %} - * {% jdoc !!java::lang.java.ast.ASTCompilationUnit#declarationsAreInDefaultPackage() %} - * {% jdoc java::lang.java.ast.JavaQualifiableNode %} - * {% jdoc !!java::lang.java.ast.ASTAnyTypeDeclaration#getQualifiedName() %} - * {% jdoc !!java::lang.java.ast.ASTMethodOrConstructorDeclaration#getQualifiedName() %} - * {% jdoc !!java::lang.java.ast.ASTLambdaExpression#getQualifiedName() %} - * {% jdoc_package java::lang.java.qname %} and its contents - * {% jdoc java::lang.java.ast.MethodLikeNode %} + * {% jdoc_old !!java::lang.java.ast.ASTAnyTypeDeclaration#getKind() %} + * {% jdoc_old java::lang.java.ast.JavaQualifiedName %} + * {% jdoc_old !!java::lang.java.ast.ASTCatchStatement#getBlock() %} + * {% jdoc_old !!java::lang.java.ast.ASTCompilationUnit#declarationsAreInDefaultPackage() %} + * {% jdoc_old java::lang.java.ast.JavaQualifiableNode %} + * {% jdoc_old !!java::lang.java.ast.ASTAnyTypeDeclaration#getQualifiedName() %} + * {% jdoc_old !!java::lang.java.ast.ASTMethodOrConstructorDeclaration#getQualifiedName() %} + * {% jdoc_old !!java::lang.java.ast.ASTLambdaExpression#getQualifiedName() %} + * {% jdoc_package_old !!java::lang.java.qname %} and its contents + * {% jdoc_old java::lang.java.ast.MethodLikeNode %} * Its methods will also be removed from its implementations, - {% jdoc java::lang.java.ast.ASTMethodOrConstructorDeclaration %}, - {% jdoc java::lang.java.ast.ASTLambdaExpression %}. - * {% jdoc !!java::lang.java.ast.ASTAnyTypeDeclaration#getImage() %} will be removed. Please use `getSimpleName()` - instead. This affects {% jdoc !!java::lang.java.ast.ASTAnnotationTypeDeclaration#getImage() %}, - {% jdoc !!java::lang.java.ast.ASTClassOrInterfaceDeclaration#getImage() %}, and - {% jdoc !!java::lang.java.ast.ASTEnumDeclaration#getImage() %}. - * Several methods of {% jdoc java::lang.java.ast.ASTTryStatement %}, replacements with other names + {% jdoc_old java::lang.java.ast.ASTMethodOrConstructorDeclaration %}, + {% jdoc_old java::lang.java.ast.ASTLambdaExpression %}. + * {% jdoc_old !!java::lang.java.ast.ASTAnyTypeDeclaration#getImage() %} will be removed. Please use `getSimpleName()` + instead. This affects {% jdoc_old !!java::lang.java.ast.ASTAnnotationTypeDeclaration#getImage() %}, + {% jdoc_old !!java::lang.java.ast.ASTClassOrInterfaceDeclaration#getImage() %}, and + {% jdoc_old !!java::lang.java.ast.ASTEnumDeclaration#getImage() %}. + * Several methods of {% jdoc_old java::lang.java.ast.ASTTryStatement %}, replacements with other names have been added. This includes the XPath attribute `@Finally`, replace it with a test for `child::FinallyStatement`. * Several methods named `getGuardExpressionNode` are replaced with `getCondition`. This affects the following nodes: WhileStatement, DoStatement, ForStatement, IfStatement, AssertStatement, ConditionalExpression. - * {% jdoc java::lang.java.ast.ASTYieldStatement %} will not implement {% jdoc java::lang.java.ast.TypeNode %} + * {% jdoc_old java::lang.java.ast.ASTYieldStatement %} will not implement {% jdoc_old java::lang.java.ast.TypeNode %} anymore come 7.0.0. Test the type of the expression nested within it. #### 6.20.0 @@ -2685,49 +2685,49 @@ No changes. **For removal** * pmd-core - * All the package {% jdoc_package core::dcd %} and its subpackages. See {% jdoc core::dcd.DCD %}. - * In {% jdoc core::lang.LanguageRegistry %}: - * {% jdoc core::lang.LanguageRegistry#commaSeparatedTerseNamesForLanguageVersion(List) %} - * {% jdoc core::lang.LanguageRegistry#commaSeparatedTerseNamesForLanguage(List) %} - * {% jdoc core::lang.LanguageRegistry#findAllVersions() %} - * {% jdoc core::lang.LanguageRegistry#findLanguageVersionByTerseName(String) %} - * {% jdoc core::lang.LanguageRegistry#getInstance() %} - * {% jdoc !!core::RuleSet#getExcludePatterns() %}. Use the new method {% jdoc core::RuleSet#getFileExclusions() %} instead. - * {% jdoc !!core::RuleSet#getIncludePatterns() %}. Use the new method {% jdoc core::RuleSet#getFileInclusions() %} instead. - * {% jdoc !!core::lang.Parser#canParse() %} - * {% jdoc !!core::lang.Parser#getSuppressMap() %} - * {% jdoc !!core::rules.RuleBuilder#RuleBuilder(String,String,String) %}. Use the new constructor with the correct ResourceLoader instead. - * {% jdoc !!core::rules.RuleFactory#RuleFactory() %}. Use the new constructor with the correct ResourceLoader instead. + * All the package {% jdoc_package_old core::dcd %} and its subpackages. See {% jdoc_old core::dcd.DCD %}. + * In {% jdoc_old core::lang.LanguageRegistry %}: + * {% jdoc_old core::lang.LanguageRegistry#commaSeparatedTerseNamesForLanguageVersion(List) %} + * {% jdoc_old core::lang.LanguageRegistry#commaSeparatedTerseNamesForLanguage(List) %} + * {% jdoc_old core::lang.LanguageRegistry#findAllVersions() %} + * {% jdoc_old core::lang.LanguageRegistry#findLanguageVersionByTerseName(String) %} + * {% jdoc_old core::lang.LanguageRegistry#getInstance() %} + * {% jdoc_old !!core::RuleSet#getExcludePatterns() %}. Use the new method {% jdoc_old core::RuleSet#getFileExclusions() %} instead. + * {% jdoc_old !!core::RuleSet#getIncludePatterns() %}. Use the new method {% jdoc_old core::RuleSet#getFileInclusions() %} instead. + * {% jdoc_old !!core::lang.Parser#canParse() %} + * {% jdoc_old !!core::lang.Parser#getSuppressMap() %} + * {% jdoc_old !!core::rules.RuleBuilder#RuleBuilder(String,String,String) %}. Use the new constructor with the correct ResourceLoader instead. + * {% jdoc_old !!core::rules.RuleFactory#RuleFactory() %}. Use the new constructor with the correct ResourceLoader instead. * pmd-java - * {% jdoc java::lang.java.ast.CanSuppressWarnings %} and its implementations - * {% jdoc java::lang.java.rule.AbstractJavaRule#isSuppressed(Node) %} - * {% jdoc java::lang.java.rule.AbstractJavaRule#getDeclaringType(Node) %}. - * {% jdoc java::lang.java.rule.JavaRuleViolation#isSupressed(Node,Rule) %} - * {% jdoc java::lang.java.ast.ASTMethodDeclarator %} - * {% jdoc java::lang.java.ast.ASTMethodDeclaration#getMethodName() %} - * {% jdoc java::lang.java.ast.ASTMethodDeclaration#getBlock() %} - * {% jdoc java::lang.java.ast.ASTConstructorDeclaration#getParameterCount() %} + * {% jdoc_old java::lang.java.ast.CanSuppressWarnings %} and its implementations + * {% jdoc_old java::lang.java.rule.AbstractJavaRule#isSuppressed(Node) %} + * {% jdoc_old java::lang.java.rule.AbstractJavaRule#getDeclaringType(Node) %}. + * {% jdoc_old java::lang.java.rule.JavaRuleViolation#isSupressed(Node,Rule) %} + * {% jdoc_old java::lang.java.ast.ASTMethodDeclarator %} + * {% jdoc_old java::lang.java.ast.ASTMethodDeclaration#getMethodName() %} + * {% jdoc_old java::lang.java.ast.ASTMethodDeclaration#getBlock() %} + * {% jdoc_old java::lang.java.ast.ASTConstructorDeclaration#getParameterCount() %} * pmd-apex - * {% jdoc apex::lang.apex.ast.CanSuppressWarnings %} and its implementations - * {% jdoc apex::lang.apex.rule.ApexRuleViolation#isSupressed(Node,Rule) %} + * {% jdoc_old apex::lang.apex.ast.CanSuppressWarnings %} and its implementations + * {% jdoc_old apex::lang.apex.rule.ApexRuleViolation#isSupressed(Node,Rule) %} **Internal APIs** * pmd-core - * All the package {% jdoc_package core::util %} and its subpackages, - except {% jdoc_package core::util.datasource %} and {% jdoc_package core::util.database %}. - * {% jdoc core::cpd.GridBagHelper %} - * {% jdoc core::renderers.ColumnDescriptor %} + * All the package {% jdoc_package_old core::util %} and its subpackages, + except {% jdoc_package_old core::util.datasource %} and {% jdoc_package_old core::util.database %}. + * {% jdoc_old core::cpd.GridBagHelper %} + * {% jdoc_old core::renderers.ColumnDescriptor %} #### 6.18.0 **Changes to Renderer** -* Each renderer has now a new method {% jdoc !!core::renderers.Renderer#setUseShortNames(List) %} which +* Each renderer has now a new method {% jdoc_old !!core::renderers.Renderer#setUseShortNames(java.util.List) %} which is used for implementing the "shortnames" CLI option. The method is automatically called by PMD, if this CLI option is in use. When rendering filenames to the report, the new helper method - {% jdoc !!core::renderers.AbstractRenderer#determineFileName(String) %} should be used. This will change + {% jdoc_old !!core::renderers.AbstractRenderer#determineFileName(String) %} should be used. This will change the filename to a short name, if the CLI option "shortnames" is used. Not adjusting custom renderers will make them render always the full file names and not honoring the @@ -2737,31 +2737,31 @@ No changes. **For removal** -* The methods {% jdoc java::lang.java.ast.ASTImportDeclaration#getImportedNameNode() %} and - {% jdoc java::lang.java.ast.ASTImportDeclaration#getPackage() %} have been deprecated and +* The methods {% jdoc_old java::lang.java.ast.ASTImportDeclaration#getImportedNameNode() %} and + {% jdoc_old java::lang.java.ast.ASTImportDeclaration#getPackage() %} have been deprecated and will be removed with PMD 7.0.0. -* The method {% jdoc !!core::RuleContext#setSourceCodeFilename(String) %} has been deprecated - and will be removed. The already existing method {% jdoc !!core::RuleContext#setSourceCodeFile(File) %} - should be used instead. The method {% jdoc !!core::RuleContext#getSourceCodeFilename() %} still +* The method {% jdoc_old !!core::RuleContext#setSourceCodeFilename(String) %} has been deprecated + and will be removed. The already existing method {% jdoc_old !!core::RuleContext#setSourceCodeFile(File) %} + should be used instead. The method {% jdoc_old !!core::RuleContext#getSourceCodeFilename() %} still exists and returns just the filename without the full path. -* The method {% jdoc !!core::processor.AbstractPMDProcessor#filenameFrom(DataSource) %} has been +* The method {% jdoc_old !!core::processor.AbstractPMDProcessor#filenameFrom(DataSource) %} has been deprecated. It was used to determine a "short name" of the file being analyzed, so that the report can use short names. However, this logic has been moved to the renderers. -* The method {% jdoc !!core::Report#metrics() %} and {% jdoc core::Report::hasMetrics() %} have +* The method {% jdoc_old !!core::Report#metrics() %} and {% jdoc_old core::Report::hasMetrics() %} have been deprecated. They were leftovers from a previous deprecation round targeting - {% jdoc core::lang.rule.stat.StatisticalRule %}. + {% jdoc_old core::lang.rule.stat.StatisticalRule %}. **Internal APIs** Those APIs are not intended to be used by clients, and will be hidden or removed with PMD 7.0.0. You can identify them with the `@InternalApi` annotation. You'll also get a deprecation warning. * pmd-core - * {% jdoc_package core::cache %} + * {% jdoc_package_old core::cache %} * pmd-java - * {% jdoc_package java::lang.java.typeresolution %}: Everything, including - subpackages, except {% jdoc java::lang.java.typeresolution.TypeHelper %} and - {% jdoc java::lang.java.typeresolution.typedefinition.JavaTypeDefinition %}. - * {% jdoc !c!java::lang.java.ast.ASTCompilationUnit#getClassTypeResolver() %} + * {% jdoc_package_old java::lang.java.typeresolution %}: Everything, including + subpackages, except {% jdoc_old java::lang.java.typeresolution.TypeHelper %} and + {% jdoc_old java::lang.java.typeresolution.typedefinition.JavaTypeDefinition %}. + * {% jdoc_old !c!java::lang.java.ast.ASTCompilationUnit#getClassTypeResolver() %} #### 6.17.0 @@ -2772,7 +2772,8 @@ No changes. **Deprecated APIs** -> Reminder: Please don't use members marked with the annotation {% jdoc core::annotation.InternalApi %}, as they will likely be removed, hidden, or otherwise intentionally broken with 7.0.0. +> Reminder: Please don't use members marked with the annotation {% jdoc core::annotation.InternalApi %}, as they will +> likely be removed, hidden, or otherwise intentionally broken with 7.0.0. **In ASTs** @@ -2781,13 +2782,18 @@ As part of the changes we'd like to do to AST classes for 7.0.0, we would like t hide some methods and constructors that rule writers should not have access to. The following usages are now deprecated **in the Java AST** (with other languages to come): -* Manual instantiation of nodes. **Constructors of node classes are deprecated** and marked {% jdoc core::annotation.InternalApi %}. Nodes should only be obtained from the parser, which for rules, means that never need to instantiate node themselves. Those constructors will be made package private with 7.0.0. -* **Subclassing of abstract node classes, or usage of their type**. Version 7.0.0 will bring a new set of abstractions that will be public API, but the base classes are and will stay internal. You should not couple your code to them. - * In the meantime you should use interfaces like {% jdoc java::lang.java.ast.JavaNode %} or {% jdoc core::lang.ast.Node %}, or the other published interfaces in this package, to refer to nodes generically. +* Manual instantiation of nodes. **Constructors of node classes are deprecated** and marked + {% jdoc core::annotation.InternalApi %}. Nodes should only be obtained from the parser, which for rules, means + that never need to instantiate node themselves. Those constructors will be made package private with 7.0.0. +* **Subclassing of abstract node classes, or usage of their type**. Version 7.0.0 will bring a new set of abstractions + that will be public API, but the base classes are and will stay internal. You should not couple your code to them. + * In the meantime you should use interfaces like {% jdoc java::lang.java.ast.JavaNode %} or + {% jdoc core::lang.ast.Node %}, or the other published interfaces in this package, to refer to nodes generically. * Concrete node classes will **be made final** with 7.0.0. -* Setters found in any node class or interface. **Rules should consider the AST immutable**. We will make those setters package private with 7.0.0. +* Setters found in any node class or interface. **Rules should consider the AST immutable**. We will make those + setters package private with 7.0.0. -Please look at {% jdoc_package java::lang.java.ast %} to find out the full list +Please look at {% jdoc_package_old java::lang.java.ast %} to find out the full list of deprecations. @@ -2799,16 +2805,16 @@ of deprecations. * The `DumpFacades` in all languages, that could be used to transform a AST into a textual representation, will be removed with PMD 7. The rule designer is a better way to inspect nodes. - * {% jdoc !q!apex::lang.apex.ast.DumpFacade %} - * {% jdoc !q!java::lang.java.ast.DumpFacade %} - * {% jdoc !q!javascript::lang.ecmascript.ast.DumpFacade %} - * {% jdoc !q!jsp::lang.jsp.ast.DumpFacade %} - * {% jdoc !q!plsql::lang.plsql.ast.DumpFacade %} - * {% jdoc !q!visualforce::lang.vf.ast.DumpFacade %} - * {% jdoc !q!velocity::lang.vm.ast.AbstractVmNode#dump(String, boolean, Writer) %} - * {% jdoc !q!xml::lang.xml.ast.DumpFacade %} -* The method {% jdoc !c!core::lang.LanguageVersionHandler#getDumpFacade(Writer, String, boolean) %} will be - removed as well. It is deprecated, along with all its implementations in the subclasses of {% jdoc core::lang.LanguageVersionHandler %}. + * {% jdoc_old !q!apex::lang.apex.ast.DumpFacade %} + * {% jdoc_old !q!java::lang.java.ast.DumpFacade %} + * {% jdoc_old !q!javascript::lang.ecmascript.ast.DumpFacade %} + * {% jdoc_old !q!jsp::lang.jsp.ast.DumpFacade %} + * {% jdoc_old !q!plsql::lang.plsql.ast.DumpFacade %} + * {% jdoc_old !q!visualforce::lang.vf.ast.DumpFacade %} + * {% jdoc_old !q!vm::lang.vm.ast.AbstractVmNode#dump(java.lang.String,boolean,java.io.Writer) %} + * {% jdoc_old !q!xml::lang.xml.ast.DumpFacade %} +* The method {% jdoc_old !c!core::lang.LanguageVersionHandler#getDumpFacade(java.io.Writer,java.lang.String,boolean) %} will be + removed as well. It is deprecated, along with all its implementations in the subclasses of {% jdoc_old core::lang.LanguageVersionHandler %}. #### 6.14.0 @@ -2826,7 +2832,7 @@ The previously available variables such as `OPTS` or `HEAPSIZE` are deprecated a **Deprecated API** -* {% jdoc core::renderers.CodeClimateRule %} is deprecated in 7.0.0 because it was unused for 2 years and +* {% jdoc_old core::renderers.CodeClimateRule %} is deprecated in 7.0.0 because it was unused for 2 years and created an unwanted dependency. Properties "cc_categories", "cc_remediation_points_multiplier", "cc_block_highlighting" will also be removed. See [#1702](https://github.com/pmd/pmd/pull/1702) for more. @@ -2840,13 +2846,13 @@ No changes. #### 6.11.0 -* {% jdoc core::lang.rule.stat.StatisticalRule %} and the related helper classes and base rule classes - are deprecated for removal in 7.0.0. This includes all of {% jdoc_package core::stat %} and {% jdoc_package core::lang.rule.stat %}, - and also {% jdoc java::lang.java.rule.AbstractStatisticalJavaRule %}, {% jdoc apex::lang.apex.rule.AbstractStatisticalApexRule %} and the like. - The methods {% jdoc !c!core::Report#addMetric(core::stat.Metric) %} and {% jdoc core::ThreadSafeReportListener#metricAdded(core::stat.Metric) %} +* {% jdoc_old core::lang.rule.stat.StatisticalRule %} and the related helper classes and base rule classes + are deprecated for removal in 7.0.0. This includes all of {% jdoc_package_old core::stat %} and {% jdoc_package_old core::lang.rule.stat %}, + and also {% jdoc_old java::lang.java.rule.AbstractStatisticalJavaRule %}, {% jdoc_old apex::lang.apex.rule.AbstractStatisticalApexRule %} and the like. + The methods {% jdoc_old !c!core::Report#addMetric(core::stat.Metric) %} and {% jdoc_old core::ThreadSafeReportListener#metricAdded(core::stat.Metric) %} will also be removed. -* {% jdoc core::properties.PropertySource#setProperty(core::properties.MultiValuePropertyDescriptor, Object[]) %} is deprecated, - because {% jdoc core::properties.MultiValuePropertyDescriptor %} is deprecated as well +* {% jdoc_old core::properties.PropertySource#setProperty(core::properties.MultiValuePropertyDescriptor,V...) %} is deprecated, + because {% jdoc_old core::properties.MultiValuePropertyDescriptor %} is deprecated as well. #### 6.10.0 @@ -2865,40 +2871,39 @@ to remove them in 7.0.0. The proposed changes to the API are described [on the w construction through builders. The builder hierarchy, currently found in the package {% jdoc_package props::builders %}, is being replaced by the simpler {% jdoc props::PropertyBuilder %}. Their APIs enjoy a high degree of source compatibility. -* Concrete property classes like {% jdoc props::IntegerProperty %} and {% jdoc props::StringMultiProperty %} will gradually +* Concrete property classes like {% jdoc_old props::IntegerProperty %} and {% jdoc_old props::StringMultiProperty %} will gradually all be deprecated until 7.0.0. Their usages should be replaced by direct usage of the {% jdoc props::PropertyDescriptor %} interface, e.g. `PropertyDescriptor` or `PropertyDescriptor>`. * Instead of spreading properties across countless classes, the utility class {% jdoc :PF %} will become from 7.0.0 on the only provider for property descriptor builders. Each current property type will be replaced by a corresponding method on `PropertyFactory`: - * {% jdoc props::IntegerProperty %} is replaced by {% jdoc !c!:PF#intProperty(java.lang.String) %} - * {% jdoc props::IntegerMultiProperty %} is replaced by {% jdoc !c!:PF#intListProperty(java.lang.String) %} + * {% jdoc_old props::IntegerProperty %} is replaced by {% jdoc !c!:PF#intProperty(java.lang.String) %} + * {% jdoc_old props::IntegerMultiProperty %} is replaced by {% jdoc !c!:PF#intListProperty(java.lang.String) %} - * {% jdoc props::FloatProperty %} and {% jdoc props::DoubleProperty %} are both replaced by {% jdoc !c!:PF#doubleProperty(java.lang.String) %}. + * {% jdoc_old props::FloatProperty %} and {% jdoc_old props::DoubleProperty %} are both replaced by {% jdoc !c!:PF#doubleProperty(java.lang.String) %}. Having a separate property for floats wasn't that useful. - * Similarly, {% jdoc props::FloatMultiProperty %} and {% jdoc props::DoubleMultiProperty %} are replaced by {% jdoc !c!:PF#doubleListProperty(java.lang.String) %}. + * Similarly, {% jdoc_old props::FloatMultiProperty %} and {% jdoc_old props::DoubleMultiProperty %} are replaced by {% jdoc !c!:PF#doubleListProperty(java.lang.String) %}. - * {% jdoc props::StringProperty %} is replaced by {% jdoc !c!:PF#stringProperty(java.lang.String) %} - * {% jdoc props::StringMultiProperty %} is replaced by {% jdoc !c!:PF#stringListProperty(java.lang.String) %} + * {% jdoc_old props::StringProperty %} is replaced by {% jdoc !c!:PF#stringProperty(java.lang.String) %} + * {% jdoc_old props::StringMultiProperty %} is replaced by {% jdoc !c!:PF#stringListProperty(java.lang.String) %} - * {% jdoc props::RegexProperty %} is replaced by {% jdoc !c!:PF#regexProperty(java.lang.String) %} + * {% jdoc_old props::RegexProperty %} is replaced by {% jdoc !c!:PF#regexProperty(java.lang.String) %} - * {% jdoc props::EnumeratedProperty %} is replaced by {% jdoc !c!:PF#enumProperty(java.lang.String,java.util.Map) %} - * {% jdoc props::EnumeratedProperty %} is replaced by {% jdoc !c!:PF#enumListProperty(java.lang.String,java.util.Map) %} + * {% jdoc_old props::EnumeratedProperty %} is replaced by {% jdoc !c!:PF#enumProperty(java.lang.String,java.util.Map) %} + * {% jdoc_old props::EnumeratedProperty %} is replaced by {% jdoc !c!:PF#enumListProperty(java.lang.String,java.util.Map) %} - * {% jdoc props::BooleanProperty %} is replaced by {% jdoc !c!:PF#booleanProperty(java.lang.String) %} - * Its multi-valued counterpart, {% jdoc props::BooleanMultiProperty %}, is not replaced, because it doesn't have a use case. + * {% jdoc_old props::BooleanProperty %} is replaced by {% jdoc !c!:PF#booleanProperty(java.lang.String) %} + * Its multi-valued counterpart, {% jdoc_old props::BooleanMultiProperty %}, is not replaced, because it doesn't have a use case. - * {% jdoc props::CharacterProperty %} is replaced by {% jdoc !c!:PF#charProperty(java.lang.String) %} - * {% jdoc props::CharacterMultiProperty %} is replaced by {% jdoc !c!:PF#charListProperty(java.lang.String) %} + * {% jdoc_old props::CharacterProperty %} is replaced by {% jdoc !c!:PF#charProperty(java.lang.String) %} + * {% jdoc_old props::CharacterMultiProperty %} is replaced by {% jdoc !c!:PF#charListProperty(java.lang.String) %} - * {% jdoc props::LongProperty %} is replaced by {% jdoc !c!:PF#longIntProperty(java.lang.String) %} - * {% jdoc props::LongMultiProperty %} is replaced by {% jdoc !c!:PF#longIntListProperty(java.lang.String) %} + * {% jdoc_old props::LongProperty %} is replaced by {% jdoc !c!:PF#longIntProperty(java.lang.String) %} + * {% jdoc_old props::LongMultiProperty %} is replaced by {% jdoc !c!:PF#longIntListProperty(java.lang.String) %} - * {% jdoc props::MethodProperty %}, {% jdoc props::FileProperty %}, {% jdoc props::TypeProperty %} and their multi-valued counterparts + * {% jdoc_old props::MethodProperty %}, {% jdoc_old props::FileProperty %}, {% jdoc_old props::TypeProperty %} and their multi-valued counterparts are discontinued for lack of a use-case, and have no planned replacement in 7.0.0 for now. - Here's an example: @@ -2917,37 +2922,37 @@ You're highly encouraged to migrate to using this new API as soon as possible, t **Architectural simplifications** -* {% jdoc props::EnumeratedPropertyDescriptor %}, {% jdoc props::NumericPropertyDescriptor %}, {% jdoc props::PackagedPropertyDescriptor %}, - and the related builders (in {% jdoc_package props::builders %}) will be removed. +* {% jdoc_old props::EnumeratedPropertyDescriptor %}, {% jdoc_old props::NumericPropertyDescriptor %}, {% jdoc_old props::PackagedPropertyDescriptor %}, + and the related builders (in {% jdoc_package_old props::builders %}) will be removed. These specialized interfaces allowed additional constraints to be enforced on the value of a property, but made the property class hierarchy very large and impractical - to maintain. Their functionality will be mapped uniformly to {% jdoc props::constraints.PropertyConstraint %}s, + to maintain. Their functionality will be mapped uniformly to {% jdoc props::PropertyConstraint %}s, which will allow virtually any constraint to be defined, and improve documentation and error reporting. The - related methods {% jdoc !c!props::PropertyTypeId#isPropertyNumeric() %} and - {% jdoc !c!props::PropertyTypeId#isPropertyPackaged() %} are also deprecated. + related methods {% jdoc_old !c!props::PropertyTypeId#isPropertyNumeric() %} and + {% jdoc_old !c!props::PropertyTypeId#isPropertyPackaged() %} are also deprecated. -* {% jdoc props::MultiValuePropertyDescriptor %} and {% jdoc props::SingleValuePropertyDescriptor %} +* {% jdoc_old props::MultiValuePropertyDescriptor %} and {% jdoc_old props::SingleValuePropertyDescriptor %} are deprecated. 7.0.0 will introduce a new XML syntax which will remove the need for such a divide - between single- and multi-valued properties. The method {% jdoc !c!:PDr#isMultiValue() %} will be removed + between single- and multi-valued properties. The method {% jdoc_old !c!:PDr#isMultiValue() %} will be removed accordingly. **Changes to the PropertyDescriptor interface** -* {% jdoc :PDr#preferredRowCount() %} is deprecated with no intended replacement. It was never implemented, and does not belong - in this interface. The methods {% jdoc :PDr#uiOrder() %} and `compareTo(PropertyDescriptor)` are deprecated for the +* {% jdoc_old :PDr#preferredRowCount() %} is deprecated with no intended replacement. It was never implemented, and does not belong + in this interface. The methods {% jdoc_old :PDr#uiOrder() %} and `compareTo(PropertyDescriptor)` are deprecated for the same reason. These methods mix presentation logic with business logic and are not necessary for PropertyDescriptors to work. `PropertyDescriptor` will not extend `Comparable` anymore come 7.0.0. -* The method {% jdoc :PDr#propertyErrorFor(core::Rule) %} is deprecated and will be removed with no intended +* The method {% jdoc_old :PDr#propertyErrorFor(core::Rule) %} is deprecated and will be removed with no intended replacement. It's really just a shortcut for `prop.errorFor(rule.getProperty(prop))`. -* `T `{% jdoc !a!:PDr#valueFrom(java.lang.String) %} and `String `{% jdoc :PDr#asDelimitedString(java.lang.Object) %}`(T)` are deprecated and will be removed. These were +* `T `{% jdoc_old !a!:PDr#valueFrom(java.lang.String) %} and `String `{% jdoc_old :PDr#asDelimitedString(java.lang.Object) %}`(T)` are deprecated and will be removed. These were used to serialize and deserialize properties to/from a string, but 7.0.0 will introduce a more flexible XML syntax which will make them obsolete. -* {% jdoc :PDr#isMultiValue() %} and {% jdoc :PDr#type() %} are deprecated and won't be replaced. The new XML syntax will remove the need +* {% jdoc_old :PDr#isMultiValue() %} and {% jdoc_old :PDr#type() %} are deprecated and won't be replaced. The new XML syntax will remove the need for a divide between multi- and single-value properties, and will allow arbitrary types to be represented. Since arbitrary types may be represented, `type` will become obsolete as it can't represent generic types, which will nevertheless be representable with the XML syntax. It was only used for documentation, but a new way to document these properties exhaustively will be added with 7.0.0. -* {% jdoc :PDr#errorFor(java.lang.Object) %} is deprecated as its return type will be changed to `Optional` with the shift to Java 8. +* {% jdoc_old :PDr#errorFor(java.lang.Object) %} is deprecated as its return type will be changed to `Optional` with the shift to Java 8. **Deprecated APIs** @@ -2960,7 +2965,7 @@ You're highly encouraged to migrate to using this new API as soon as possible, t **For internalization** -* The implementation of the adapters for the XPath engines Saxon and Jaxen (package {% jdoc_package :xpath %}) +* The implementation of the adapters for the XPath engines Saxon and Jaxen (package {% jdoc_package_old :xpath %}) are now deprecated. They'll be moved to an internal package come 7.0.0. Only {% jdoc xpath::Attribute %} remains public API. * The classes {% jdoc props::PropertyDescriptorField %}, {% jdoc props::builders.PropertyDescriptorBuilderConversionWrapper %}, and the methods