chore(deps): update dependency docma to v3

[renovate]

This PR contains the following updates:

Package	Change	Age	Adoption	Passing	Confidence
docma	^1.5.3 -> ^3.0.0

---

Release Notes

onury/docma (docma)

v3.2.2

Compare Source

Fixed

• An issue where enumeration value would be incorrectly displayed as undefined in docs parsed from ES5 code.
• An issue where jsdoc.predicate (or jsdoc.filter) option would not be taken into account.
• An issue where favicon would not be copied over to the output dir.
• (Zebra Template) An issue where some special characters within the location hash would cause an error.
• Invalid assignment error due to ES2015 syntax.

Added

• Support for handling notation with multiple sub-types. e.g. Map<String, Object>. (PR #​65 by @​MaienM)

Changed

• Improved / cleaner symbol names and long names. This also fixes a JSDoc bug that unnecessarily and incorrectly wraps the last level of the notation in quotes and brackets.
• Updated dependencies to their latest versions.

v3.2.1

Compare Source

v3.2.0: Docma v3.2.0

Compare Source

See changes here and documentation for a live demo.

If you're migrating from Docma v.2.x, please read the CHANGELOG thoroughly before updating your Docma configuration.

v3.1.0

Compare Source

Fixed

• An issue with "path" routing which led to 404 page, occurred when a (deep) route was refreshed or loaded directly. (Due to a bug in core dependency.) Fixes #​62.
• An issue where a (harmless) TypeError was thrown when debug is enabled.
• An issue with $docmaLink due to missing trailing slash, when routing method is "path".

Added

• (Zebra Template) Added JSDoc @default tag support for symbols. Fixes #​60.
• (Zebra Template) Added option contentView.faLibs that defines FontAwesome libraries to be included, such as solid, regular, brands. Set to null to completely exclude FontAwesome from the output. See Zebra documentation. Fixes #​63.
• (Zebra Template) Added option contentView.faVersion that defines FontAwesome icon library version to be included.

Changed

• Improved SPA route handling.
• Updated dependencies to latest versions.

v3.0.0

Compare Source

Changed

• BREAKING: Dropped support for Node.js versions 6 & 7. Requires Node.js v8 and later. This change is due to updates to the core dependencies such as fs-extra, jsdoc-x and jsdom.
• Improved path/query routing.
• BREAKING: Linking logic has some changes.
• (Zebra template) Improved support for constant symbols.

Added

• Ability to force parser type on defined files/paths; by appending a suffix. For Markdown, append :md or :markdown. For HTML, append :htm or html. For example, LICENSE:md will force-parse LICENSE file as markdown. file.partial:html will force-parse file.partial as HTML.
• Ability to create deeper paths for named groups/routes. e.g. mylib/latest
• Support for favicon. Set app.favicon to your ICO file's local path.
• Support for collapsable markdown (i.e. with <details> and <summary> tags). This is great for generating styled collapsable lists (such as F.A.Q.) from your markdown files. If a bookmark (id) is passed in the location hash, that item will auto-expand. See [Docma F.A.Q.][faq] for an example. Note that Edge does not support details/summary tags yet. All other modern browsers have support.
• Ability to hide or remove specific, partial content from Docma output. For example if you want some part of your README to be visible in GitHub repo but not in your Docma generated documentation... See this for details.
• New CLI option (-b or --base) for docma serve command to override/set the base path.
• (Zebra Template) Added support for collapsable markdown (i.e. with <details> and <summary> tags).

Fixed

• An issue where documentation build would fail due to a symbol name being a non-string value. Fixes #​54.
• An issue where the web app would throw Uncaught TypeError when invalid JSDoc type specified for @returns. Fixes #​55.
• Fixed ["Reverse Tabnabbing" vulnerability][tabnabbing] with generated documentation links. (This is also fixed for Zebra template.)
• An issue where base tag would not be added to the head of main document.
• An issue where Docma would not set default app.base path to / as expected. Fixes #​59.
• An issue where symbol link would be parsed as absolute path rather than relative. Fixes #​50.
• (Zebra template) Fixed an issue where tags such as @constant and @module would cause an Uncaught TypeError. Fixes #​41 and #​45.

v2.1.0

Compare Source

Docma CLI

Thanks to @​feugy for this PR.

Added

• serve command now takes conf.app.base parameter into consideration, and will redirect http://localhost:9000/ to it.

Fixed

• serve command can handle conf.app.dest relative path, and resolves them against current working directory.
• A file name issue that produces cannot find module error in case-sensitive systems. Fixes #​38.

Changed

• Renamed the --quite option to --quiet. Alias -q remains the same.

Default Template - Zebra v2.1.0

Added

• Partial support for TypeScript-style type notation. e.g. Promise<Number> or Number[], etc...

Fixed

• An issue where deeper levels of tree nodes were not properly aligned, when sidebar.outline is set to "tree".
• An issue where some symbol names were unnecessarily scroll-animated on hover. Firefox was affected.
• An issue where multiple return types were listed out of style.

Changed

• When sidebar.itemsOverflow is set to "crop" (default); symbol names are faded-out on their edges, instead of using ellipsis (which behaves differently on browsers).

v2.0.0

Compare Source

This is a big release with some breaking changes.
Please read this changelog thoroughly before updating your Docma configuration.

Docma (Builder)

Added

• Support for documenting code with ES2015 syntax. (JSDoc and jsdoc-x dep. update.) Fixes #​18 and #​21.
• assets build configuration which provides ability to copy defined asset files/directories to build directory; so you can use/link to non-source, static asset files (such as images, PDFs, etc). See [build configuration][build-config]. Fixes #​29.
• Pre-build and post-build process support for Docma templates. See Docma Templates documentation.
• markdown.xhtml option for build configuration.
• Docma version compatibility check for Docma templates.
• clean option that specifies whether to empty destination directory before the build. Default is false.
• Build statistics logs to console output. Now, displaying gzipped size of generated (docma-web) script, in addition to minified size; and more detailed summary of routes configured.

Fixed

• An issue where the builder would not check for duplicate route names with the same route type (and silently overwrite the generated content file).
• An issue where compiled template scripts were altered when full-debug is enabled.
• An issue with redirecting a page when the routing method is set to "path".
• An issue with images in HTML (generated from markdown) that would overflow out of page. Now, limiting the image width to 100% of parent container while keeping the aspect ratio.
• An issue with generated heading ids when building docs from markdown. Other HTML tags contained within the heading were not ignored, resulting in too complex ids (bookmarks).

Changed

• BREAKING: Due to several upgrades (such as jsdom), Docma v2+ requires Node.js v6 or newer.
• Greatly improved the symbol sorting logic ([jsdoc-x][jsdoc-x]). You can now sort by scope, by access type, by kind, grouped or alphabetic (default). See jsdoc.sort option in [build configuration][build-config].
• The destination directory is not auto-cleaned anymore before the build. Use clean option for the old behavior. Fixes #​34.
• Improved markdown parser. Both <h1 /> and <h2 /> tags are now followed with a <hr/>, like on GitHub.
• Updated core dependencies to their latest versions.
• Migrated all code to ES2015.
• BREAKING: Docma templates are now node modules. Docma still comes with an updated, built-in default template (Zebra). But templates designed for Docma v1.x will not work with Docma v2.x.

Removed

• For template authors only:
  • BREAKING: docma.template.json file that defines the template build and configuration options is dropped in favor of template module main (JS) file or package.json. There are several other improvements. See updated documentation on Creating Docma Templates.
  • BREAKING: compile property of template configuration is removed. Now, scripts or less/sass files of the template should be pre-compiled. This is logical and speeds up the documentation build process of Docma.

Docma CLI

Added

• Option --clean to empty destination directory before the build.
• Command docma serve for starting a static server for serving / testing the generated SPA.
• Command docma template init for initializing a new Docma template project.
• Command docma template doctor for diagnosing a Docma template. Useful for template authors.

Changed

• Dropped default configuration file name docma.config.json in favor of docma.json (shorter) and .docma.json if you need to hide it. This does not break anything, you can still use the former if you want.
• CLI will now auto-check for a docma.json (or .docma.json) file in the current working directory if -c option is omitted.
• Options -v (lowercase) and -V (uppercase) are swapped. -v gets the Docma version now (alias --version). And -V is --verbose.

See [CLI documentation][cli] for detailed information on updated CLI.

Docma Web Core

Added

• Event navigate that's triggered either when route is changed or on hash-change.
• Each symbol in docma.apis[name].documentation instances, now has a .$docmaLink property.
• New utility methods to DocmaWeb.Utils: .type(), .getSymbolLink(), .getLevels(), .getParentName(), .getParent(), .isPackagePrivate(), .isEvent(), .isGenerator(), .isCallback(), .isConstant(), .isInterface(), .isExternal() and .isMixin().
• Utility methods .getCodeTags(), .getFormattedTypeList(). Fixes #​33.
• Utility method .trimNewLines(). This also has a dust filter $tnl.

Fixed

• Broken bookmark links due to URI encoded characters after hash (#). e.g. when navigated to #MyClass%7EInnerObject instead of #MyClass~InnerObject.
• An issue with DocmaWeb.Utils.getLongName(), occured after JSDoc core upgrade.
• currentRoute parameter of the route event. Passing null instead of empty route object when route does not exist.
• An issue with DocmaWeb.Utils.isClass() utility method where meta.code.type is not set to ClassDeclaration.
• DocmaWeb.Utils.isProperty() utility method. It'll now return false if symbol is a method/function. This also affects the following methods: .isStaticProperty(), .isInstanceProperty().

Changed

• BREAKING: Docma utility methods are moved to DocmaWeb.Utils static namespace (formerly under docma.utils).
• DocmaWeb.Utils.getSymbolByName() signature is changed.
• Updated web-core dependencies.

Docma Template API

Changed

• Docma templates are now node modules. This is the initial Template API. See updated documentation on Creating Docma Templates.

Default Template - Zebra v2.0.0

Added

• Support for @example <caption>Title</caption>. Fixes issue #​14.
• Support for @hideconstructor tag. Fixes issue #​21.
• Support for @event, @emits (and alias @fires) tags. Fixes issue #​35.
• Support for @generator and @yields tags.
• Support for rest parameters (i.e. ...args).
• Support for @since tag.
• Support for folding child members of parent symbols. Added template option sidebar.itemsFolded (boolean) for setting the initial state. Fixes issue #​26.
• Template option sidebar.toolbar (boolean) that toggles a tiny toolbar below the search box, for switching symbol list outline or quick-filtering symbols by symbol-kind. Enabled by default.
• Template option logo (String|Object) specifies the URL of your logo. If you need separate logos for dark and light backgrounds set this to an object. i.e. { dark: String, light: String }. Recommended size of a logo image is 120 x 120 pixels.
• Template option symbols.autoLink (Boolean|String) specifies whether documented types should be auto-linked to internal paths (i.e. Docma route if type/object definition is within the generated documentation) or external URLs (MDN docs if it's a JS or Web-API built-in type/object such as String); or both. Thanks to @​warpdesign for the idea.
• Template options symbols.params, symbols.props and symbols.enums all taking a string value, either "list" (default) or "table"; defining the layout style for parameters, properties and enumerations. If you like the design in previous versions, set these to "table".
• Template option sidebar.animations and navbar.animations (Boolean) specifies whether CSS transitions and animations should be enabled for navbar, sidebar and listed symbols.
• Template option contentView.bookmarks option (Boolean|String) which automatically adds bookmark links to headings to content generated from markdown files. Default: false.
• generator badge for generator functions.

Fixed

• Some spacing issues with class descriptions. Empty tables are auto-removed now.
• A JSDoc issue where the constructor would be incorrectly marked as alias.
• An anchor/bookmark issue with multiple symbols having the same id.
• Sub-symbols that are listed in a table, will not wrap to new line anymore.
• An issue where the (heading) title would be hidden under the nav-bar when navigated via a local bookmark on a page, generated from a markdown file. Also improved spacing for headings.
• An issue where the page would not scroll/jump to the bookmark on initial load; when the URL has a location hash.
• Pre/code elements not to wrap content. Now, horizontally scrollable (like on GitHub).
• An issue with sidebar symbol names auto-resizing incorrectly in some cases. Also improved performance by caching font-size for each item.
• hidden meta issue. If symbol had no class description, tags such as @author, @version and @copyright would not be shown.
• Sidebar scrollbars that were not fully visible.
• Some issues with navbar margins when sidebar is disabled.
• Sidebar and navbar title so that they allow longer strings without breaking.

Changed

• Default template finally has a name :) - Zebra.
• BREAKING: You need Docma v2+ for latest Zebra template to work.
• Improved symbol listing styles and performance. Using CSS transitions instead of JS manipulation. Also; when search is active, outline is temporarily set to "flat" so that you see the parent of the symbol. When search box is cleaned, it's set back to the initial template setting. (e.g. "tree" if set).
• Improved @example outputs. If there are multiple examples for a symbol, they will be numbered now.
• Improved nested bullet list spacing, for better readability.
• Improved UI and responsive layout. On small screens, sidebar auto-collapses; top navbar turns into hamburger menu. Also, truly printable.
• Improved template option .badges (default: true) to also accept a string value for custom bullets instead of badges.
• Improved template option .title to also accept an object { label:String, href:String } so you can link it.
• Various other improvements and clean up.

Deprecated

• The template options object structure is changed and a couple of options are renamed. Old structure is still supported and it won't break anything but this support will be removed in future versions. See documentation for the new & improved structure.

Removed

• BREAKING: icomoon selection of icons (and ico- CSS prefix) in favor of FontAwsome (v5) and SVG icons support.
• Bootstrap and its dependencies (css and js). Also, cleaned up all unused styles.

---

Configuration

📅 Schedule: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).

🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.

♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 Ignore: Close this PR and you won't be reminded about this update again.

---

• If you want to rebase/retry this PR, check this box

---

This PR has been generated by Mend Renovate. View repository job log here.

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

---

Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media?

Share

• X
• Mastodon
• Reddit
• LinkedIn

Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>.
  • Generate unit testing code for this file.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit testing code for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai generate interesting stats about this repository and render them as a table.
  • @coderabbitai show all the console.log statements in this repository.
  • @coderabbitai read src/utils.ts and generate unit testing code.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (invoked as PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Additionally, you can add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.

CodeRabbit Configration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.