Skip to content

Latest commit

 

History

History
118 lines (85 loc) · 7.53 KB

CHANGELOG.md

File metadata and controls

118 lines (85 loc) · 7.53 KB

@fluid-tools/api-markdown-documenter

0.17.1

  • Updates TSDoc node handling to emit a warning in place of an error when an embedded HTML tag is encountered. Also updates the logged notice to include the tag that was encountered.
  • Fixes a bug where the default transformation for the API Model page did not correctly account for the skipPackage configuration, and would list packages that were not intended for inclusion in the generated docs suite.

0.17.0

  • Updates HTML rendering APIs to operate on HAST domain trees from documentToHtml, and leverage existing rendering libraries (hast-util-to-html and hast-util-format) rather than maintaining bespoke rendering code.
    • Updates existing HtmlRenderer.renderApiModel and HtmlRenderer.renderDocument APIs to leverage the new flow.
    • Also adds HtmlRenderer.renderHtml function for direct rendering of HAST format generated by documentToHtml.
  • Fixed a bug where text formatting was not applied correctly in some cases in the toHtml transformation.

⚠ BREAKING CHANGES

  • Formatting of generated HTML strings changes with this update.
  • Support for embedded HTML contents in TSDoc comments has been removed. The TSDoc parser has some half-baked support for preserving HTML tags in its output, despite the TSDoc spec making no claims about supporting embedded HTML. But it does so in a structure that is difficult to handle correctly, assuming that the output language can support arbitrary HTML contents, and that it is safe to output the contents raw and unsanitized. As a result, this library's support for such contents was similarly half-baked, and difficult to maintain. VSCode Intellisense, as a comparison, chooses to completely ignore HTML tags, and simply render the inner contents ignoring any HTML decorators. This library has adopted the same policy. If you depended on HTML content preservation, this change will break you.

0.16.1

  • Promote toHtml transformation functions to @public. Updates the API surface to be more flexible, allowing users to specify only a partial config, or the full transformation context if they have it.

0.16.0

  • Added the following new utility function to ApiItemUtilities:
    1. ancestryHasModifierTag: Checks if the provided API item or ancestor items are tagged with the specified modifier tag.

Beta

  • Adds prototype functionality for "linting" an API Model (i.e., the set of packages whose docs are published as a single "suite"). Can be invoked by importing lintApiModel from @fluid-tools/api-markdown-documenter/beta. Returns a set of TSDoc-related "errors" discovered while walking the API Model.
    • The primary goal of this tool is to detect issues that API-Extractor cannot validate on a per-package basis when generating API reports. For now, this is limited to validating @link and @inheritDoc tags to ensure that symbolic references are valid within the API Model.

⚠ BREAKING CHANGES

  • Updated loadModel to take a configuration object, rather than individual parameters.
    • Also allows default use of the console logger when no logger is explicitly given.

0.15.0

  • Added the following new utility functions to ApiItemUtilities:
    1. getCustomBlockComments: Gets all custom block comments associated with the provided API item.
      • Will not include built-in block comment kinds like @see, @param, etc.
    2. getModifierTags: Gets all modifier tags associated with the provided API item.
      • Will include built-in modifier tags like @sealed, release tags, etc.
    3. hasModifierTag: Checks if the provided API item is tagged with the specified modifier tag.

⚠ BREAKING CHANGES

  • The following existing APIs were updated to return readonly arrays, where they were not previously readonly:
    • getExampleBlocks
    • getSeeBlocks
    • getThrowsBlocks

0.14.0

  • Allow configuration of "alerts" in child item tables.
    • Default behavior can be overridden via the the getAlertsForItem option.

⚠ BREAKING CHANGES

  • Update default policy for getHeadingTextForItem to not insert (BETA) and (ALPHA) postfixes based on release tags. If this is the desired behavior, it can be replicated by overriding getHeadingTextForItem to do so.

0.13.0

⚠ BREAKING CHANGES

  • Removed support for generating front-matter. Front-matter generation was never properly designed, and did not fit well into the transformation flow as it was implemented. If you require front-matter in the documents you generate, you can inject it by rendering the DocumentNodes generated by transformApiModel.

0.12.2

  • Fixed an issue where variable item tables did not include type information in default ApiItem transformations.
  • Add variable and property type information to associated details sections in default ApiItem transformations.
  • Further improved error messages when an unexpected child kind is encountered when iterating over children in default ApiItem transformations.

0.12.1

  • Improved error messages when an unexpected child kind is encountered when iterating over children in default ApiItem transformations.

0.12.0

  • Added functionality for transforming Documentation Domain trees to hast. The main entrypoint for this is: documentToHtml.
  • Updated the package to emit ESM only.
  • Fixed a bug where inline tags (other than {@link} and {@inheritDoc}, which are handled specially by API-Extractor) were not handled and resulted in errors being logged to the console. Such tags are now handled in the following way:
    • {@label} tags are simply omitted from the output (they are intended as metadata, not documentation content).
    • Other custom inline tags are emitted as italicized text.
  • Fixed a bug where pre-escaped text contents (including embedded HTML content) would be incorrectly re-escaped.
  • Fixed a bug where type parameter information was only being generated for interface and class items.
  • Adds "Constraint" and "Default" columns to type parameter tables when any are present among the type parameters.
  • Fixed a bug where getter/setter properties under interface items did not get documentation generated for them.

⚠ BREAKING CHANGES

  • The package now outputs ESM only. Consumers will have to migrate accordingly.
  • DocumentationNode now has a required isEmpty property. Implementations will need to provide this.
  • Update the signature of createTypeParametersSection to always generate a SectionNode when called, such that consumers don't have to handle a potentially undefined return value. If the consumer wants to omit the section (for example when the list of type parameters is empty), they can make the call conditional on their end.
  • Removed createDocumentWriter, and exported DocumentWriter is now an interface rather than a class. A DocumentWriter may be instantiated via DocumentWriter.create (or you can use your own implementation, which was not previously supported).
  • Update typescript dependency from 4.x to 5.x.