JSDoc的默认"主页"文本和内容

Question

从Node.js运行基本的JSDoc编译/渲染之后:

jsdoc file1.js file2.js

我使用目录"out"中的默认模板获得格式良好的文档.几乎所有都如预期!

但是在打开文档时,它总是在index.html页面上显示"Home",在该初始页面上没有内容,并且在侧边栏导航中显示"Home".

我如何以及在何处注明项目名称以取代"Home"？我还想看一个项目描述,以及作者和版权信息.

这似乎是JSDoc中最基本的事情,但我无法找到这些信息!基于我在互联网上发现的一些随机文章,我尝试了以下内容:

/** 
 * This JavaScript file contains foo bar baz...
 * 
 * @projectname Project Name
 * @version 0.1
 * @author Greg Pettit
 * @copyright 2015
 * 
 */

但我没有爱.

[编辑添加:]

发现了@file/@fileOverview/@overview(所有同义词)指令,这有点帮助,因为我现在可以为每个文件描述和设置版权/作者信息:

/** 
 * @file Project description which renders below the individual filename and therefore isn't a real overview blurb.
 * 
 * @version 0.1
 * @author Greg Pettit
 * @copyright 2015
 * 
 */

这留下了两个"问题"来解决:

1. 概述说明; 我认为@file可以满足我的大多数需求,但由于它是每个文件,我仍然会喜欢在包含文件的描述之前出现的"简介"类型段落或概述段落.

2. 用自定义文本替换"Home"文本

Answer 1

生成主页

创建markdown文件README.md

生成jsdoc:

$ jsdoc path/to/js path/to/readme/README.md

要了解更多有关此访问的官方文档

更改"主页"文字

我不认为这是一种正确的方法,但这是有效的.

如果在工作目录中的项目查找模板文件中安装了jsdoc,我的是:

./node_modules/jsdoc/templates/default/publish.js

然后使用搜索命令搜索"Home"并替换为您的文本,下一步是在生成jsdoc时指定模板:

 $ jsdoc ./src/scripts/ ./README.md -t node_modules/jsdoc/templates/default/

Answer 2

我无法发表评论，因此我将根据“ \ npm \ node_modules \ jsdoc \”中文件的说明，在此处添加注释，以阐明如何在不更改默认模板的情况下完成原始问题中的所有操作模板”文件夹，其中说明了如何创建自己的模板。下面概述了将生成的js文档中的“首页”标题更改为项目特定标题（例如，“ MyDescription”）并在主页顶部包括概述框的步骤。

脚步

1. 首先，要使通用概述进入js文档主页的顶部，您将按照上面的答案和链接制作用Markdown编写的名为README.md的简单文本文件。如果该文件的路径包含在命令行中（如上所示）或在conf.json文件中添加了引用，则整个文本将显示在页面顶部，在这种情况下，您可以将其jsdoc -c pathTo\conf.json用于命令行（请参见下面第4项中的示例）。（正如该链接所说明的，您可以使用Markdown创建任何名称或扩展名的文件，并且告诉jsdoc在哪里找到它）。
2. 将默认模板（\npm\node_modules\jsdoc\templates\default）的文件夹和内容复制到新目录，将新文件夹重命名为myTemplate。
3. 使用上面的建议来更改“主页”文本，搜索publish.js在新myTemplate文件夹中命名的文件，并将“主页”替换为“ MyDescription”。这里需要注意两点：文件名必须保持不变publish.js，并且在该行的原始“ publish.js”中的两个位置出现“ Home”

   var nav ='<h2> <a href="index.html">首页</a> </ h2>';

   和线开始generate('Home',...。

4. 告诉jsdoc生成器在哪里可以找到您的自定义模板（myTemplate文件夹）和概述文件（“ README.md”）。如果创建在文本编辑器中命名的文件（例如下面的文件，该文件指定了文档的来源，目标等），则可以添加-t pathTo\myTemplate到命令行，也可以使用非常短的命令行。通过告诉doc生成器在“源”部分中使用该文件，将概述放到主页中，并使用“选择”部分中的新文件夹将标题从“首页”更改为新标题“ MyDescription”。。jsdoc -c pathTo\conf.jsonconf.jsonREADME.mdmyTemplate

   {
       "tags": {
           "allowUnknownTags": true,
           "dictionaries": ["jsdoc","closure"]
       },
       "opts": {
           "template": "pathTo/myTemplate",
           "destination": "pathTo/myJScriptDocs",
           "recurse": true
       },
       "source": {
           "includePattern": ".+\\.js(doc)?$",
           "excludePattern": "(^|\\/|\\\\)_",
           "include": ["pathTo/myJSSources", "pathTo/README.md"]
       },
       "plugins": [],
       "templates": {
           "cleverLinks": false,
           "monospaceLinks": false
       }
   }
   

Answer 3

您还可以向一个或多个源文件添加@file(或)。@fileOverview

所有文件的概述部分都将包含在 JSDoc 主页上。如果您还将自述文件提供给 JSDoc，则文件概述将放置在自述文件内容之后。

例子：

/**
 * @file index.js is the root file for the example.
 * It kicks things off.
 * @author Your name goes here
 * @see <a href="https://developers.docusign.com">DocuSign Developer Center</a>
 */