JSR文档生成器支持自定义模块导入标识符

在JavaScript和TypeScript模块开发中，当使用通配符导入(即import * as)时，开发者通常需要为导入的模块命名一个标识符。JSR文档生成器最近新增了一项功能，允许模块作者自定义这个标识符，而不是默认使用mod。

功能背景

在之前的版本中，JSR文档生成器在处理通配符导入时，会固定使用mod作为标识符。例如：

import * as mod from "example-module"

这种固定命名方式虽然简单，但不够灵活，特别是当模块名称较长或需要更语义化的标识符时。

新功能实现

现在，模块作者可以通过在模块的JSDoc注释中添加@module标签来自定义导入标识符。具体用法如下：

/**
 * OAuth 2.0和OIDC协议的实现
 * 
 * @module oauth
 */

这样，在生成的文档中，使用示例会显示为：

import * as oauth from "@panva/oauth4webapi"

使用注意事项

1. 简洁性优先：建议使用简短且有意义的标识符名称
2. 避免冲突：确保自定义标识符不会与模块内部导出名称冲突
3. 文档影响：@module标签的值会同时影响文档中的导入示例和模块概述页面的标题

最佳实践

对于大多数模块，建议保持标识符与模块名称的主要部分一致。例如：

// 对于"@company/data-utils"模块
/**
 * 数据操作工具集
 * @module dataUtils
 */

这项改进使得生成的文档更加贴近实际使用场景，提高了代码示例的可读性和实用性。开发者现在可以根据模块的实际用途和上下文，选择最合适的导入标识符名称。