Upgrading dartdoc 7 to 8
Breaking7.0.2 → 8.3.4Breaking24Platform3Deprecated7New14Changed32Fixed27Other6
BreakingUpgrade verdict
24 breaking changes and 3 platform requirement changes.
In plain terms
- Documentation comments can no longer link to the containing element using `[this]`; write `this [Foo]` or use backticks around `this` instead.
- Removes the unnecessary Privacy mixin.
- The `@example` tag no longer works in documentation comments.
- Libraries no longer get an explicit name assigned by dartdoc.
Must act Top 5 of 34 that need code or config changes
Dart SDK requirement changed in 8.3.3: ^3.0.0 → ^3.6.0.
Drops cli_util.
Moves analyzer ^6.3.0 → ^7.4.4, markdown ^7.1.0 → ^7.2.1. Your build may pick other versions.
What you must change
Breaking24
Removes support for
[this] as a comment reference.[this]Removes the unnecessary Privacy mixin.
PrivacyRemoves support for the
@example directive.@exampleRemoves explicit library names.
Removes the
--format flag that allowed generating Markdown-formatted docs.--formatRemoves @hideConstantImplementations fully.
@hideConstantImplementationsRemoves the Class assert for ClassTypedef.
ClassClassTypedefRemoves the image directive.
imageRemoves the samples directive.
samplesRemoves the api directive.
apiRemoves ElementType.canHaveParameters.
ElementType.canHaveParametersRemoves DefinedElementType.element and DefinedElementType.isParameterType.
DefinedElementType.elementDefinedElementType.isParameterTypeMoves library page URLs from "library-name-library.html" to "index.html" in the same directory, leaving a redirect at the old location.
Makes
ContainerAccessor.isInherited a final field.ContainerAccessor.isInheritedMakes
PackageGraph.analysisContext a private field.PackageGraph.analysisContextMakes
CommentReferenceParser.codeRef private.CommentReferenceParser.codeRefMakes
PackageGraph.allLibraries private.PackageGraph.allLibrariesMakes almost all elements in package_builder private.
package_builderMakes several members on PackageGraph private.
PackageGraphMakes packageName, name, libraryName, and specialFileUri private in SpecialClass.
SpecialClasspackageNamenamelibraryNamespecialFileUriMakes PackageMeta.pathContext private.
PackageMeta.pathContextMakes ElementType subclass constructors private.
ElementTypeMakes TypeImplementing.directInterfaces private.
TypeImplementing.directInterfacesRestricts InheritingContainer members hasPublicInheritedMethods, inheritedFields, publicInheritedFields, and publicInheritedMethods to testing only.
InheritingContainerhasPublicInheritedMethodsinheritedFieldspublicInheritedFieldspublicInheritedMethodsPlatform3
Requires Dart 3.6 or later.
Requires Dart 3.5 or later.
Requires Dart 3.2.0 or later.
Deprecations to plan for
Deprecated7
Deprecates the
missingCodeBlockLanguage warning in favor of the missing_code_block_language_in_doc_comment lint rule.missingCodeBlockLanguagemissing_code_block_language_in_doc_commentDeprecates the
--nodoc option.--nodocDeprecates the
--resources-dir option.--resources-dirDeprecates the
--include-externals option.--include-externalsDeprecates the --templates-dir option.
--templates-dirDeprecates options.dart ahead of removal in the next major release.
options.dartDeprecates public exports in lib/dartdoc.dart ahead of removal in the next major release.
lib/dartdoc.dart