CN117461023A - 从通用规范为许多编程语言产生惯用软件文档 - Google Patents

Abstract

计算机实施的技术解决了从以通用规范编程语言编写的通用规范为许多编程语言产生惯用软件文档的若干问题。所述技术可由文档生成器计算机程序采用，所述文档生成器计算机程序将所述通用规范翻译成用于许多不同编程语言目标中的每一者的软件编程接口文档。所述技术还可由源到源编译器采用，所述源到源编译器除了将所述通用规范编译成所述不同目标语言以外还并入有从所述通用规范为许多不同编程语言目标中的每一者生成文档的技术。

Description

从通用规范为许多编程语言产生惯用软件文档

技术领域

本公开涉及计算机编程语言。更具体来说，本公开涉及用于从通用规范为许多编程语言产生惯用软件文档的计算机实施的技术。

背景技术

计算机是用于执行各种各样任务的极强大工具。计算机程序是用于使用计算机系统来实现定制处理任务的通用机制。典型程序是编译成可执行形式的一组经编程指令(源代码)。然后，可执行形式由计算机系统执行以实现任务。举例来说，一组C编程语言指令可被编译成一组×86处理器可执行指令。然后，所述一组处理器可执行指令可由×86兼容处理器执行以实现处理任务。

在如由人类计算机程序员编程的一组经编程指令与可执行形式之间，编译器通常用作翻译器。本质上，编译器保护程序员免于知晓或甚至无需担心底层可执行形式细节。通常，由程序员编写的所有经编程指令都由编译器翻译。举例来说，编译器可执行数据类型检查、符号表构造、寄存器分配及指令调度，所有这些都不需要程序员了解底层编译器实施方式。以这种方式，编译器向程序员提供使用高级编程语言在更高级别上推理及表达处理任务的工具，这减轻了程序员担心低级别执行细节的认知负担。编译器的一般构造及操作在本领域中是众所周知的。参见例如Aho,A.、Sethi,R.及Ullman,J.的“编译器：原理、技术及工具(Compilers:Principles,Techniques,and Tools)”，第二版，2007年。

一些编译器的一个目的是交叉编译。交叉编译器可被定义为从一个输入产生两个或更多个输出的编译器，其中输出比输入更接近于最终可执行形式。举例来说，交叉编译器可接受以人类及计算机可读两者的源编程语言编写的源代码作为输入，并产生源代码的多种不同可执行形式作为输出。举例来说，考虑了C编程语言的交叉编译器。此种交叉编译器可从C源代码产生×86可执行文件(例如，用于在配置有MICROSOFT WINDOWS操作系统的计算机上执行)、ARM可执行文件(例如，用于在配置有ANDROID操作系统的移动计算装置上执行)及WASM可执行文件(例如，用于在由web浏览器应用支持的虚拟堆栈机器上执行)。

还存在源到源编译器。源到源编译器可被定义为这样的编译器：接受以人类及计算机可读两者的源编程语言编写的源代码作为输入，并输出用于各自也是人类及计算机可读两者的一个或多个不同编程语言目标的源代码。然后，不同编程目标可由相应编译器进一步编译成可执行形式。举例来说，HAXE编译器可将以HAXE编程语言编写的源代码翻译成一些结构上类似的编程语言目标。关于HAXE的更多信息可在互联网上在haxe.org互联网域中找到。

不同编程语言社区使用不同工具集来生成用于软件编程接口的文档。举例来说，JAVA编程语言社区使用JAVADOC文档生成器，PYTHON编程语言社区使用PYDOC文档生成器，C++编程语言社区使用DOXYGEN文档生成器，等等。每一文档生成器以不同形式生成文档。因此，不同社区的成员期望软件编程接口文档能够以不同方式进行格式化，所述方式取决于手边的特定编程语言而有所变化。

本文中所公开的技术解决了这个问题及其他问题。

本节中所描述的方法是可追求的方法，但未必是先前所设想或所追求的方法。因此，除非另有指示，否则不应假设本节中所描述的任何方法仅仅因为包含在本节中就有资格作为现有技术。

附图说明

在附图的各图中，所述技术是通过示例方式而非通过限制方式来图解说明的，并且其中相同元件符号指代类似元件，且在附图中：

图1是用于从通用规范为许多编程语言产生惯用软件文档的软件文档生成系统的示意图。

图2是软件文档生成系统的文档片段翻译器中的翻译阶段的流程图。

图3是用于从通用规范为许多编程语言产生惯用软件文档的过程的流程图。

图4是可在所述技术的实施方式中使用的示例性基本计算装置的框图。

图5是可用于控制图4的基本计算装置的操作的示例性基本软件系统的框图。

发明内容

下文具体实施方式的总体概述章节提供了从通用规范为许多编程语言产生惯用软件文档的技术的有用概述。

具体实施方式

在以下描述中，出于解释目的，陈述了众多具体细节以提供对所述技术的透彻理解。然而，显而易见的是，所述技术可在没有这些具体细节的情况下实践。在其他实例中，众所周知的结构及装置是以框图形式展示的，以避免不必要地模糊所述技术。

词汇表

提供以下定义是为了说明性目的而不是限制性目的，以帮助理解本技术的公开内容：

清晰结构化文本：术语“清晰结构化文本”是未经特殊培训的人可破译但也是机器可解释的结构化文本。举例来说，在以下示例性微博服务消息“@catlover，您2020-09-30的照片可在https://cat.photos处获得”，文本“@catlover”、工业标准组织(ISO)格式的日期以及URL对机器及没有经过最低限度训练的人类两者都有意义。

交叉编译器：“交叉编译器”是从一个输入产生两个或更多个许多输出的编译器。

编译器：“编译器”消耗适合人类及机器消耗两者的输入，例如以通用规范编程语言编写的计算机程序或计算机程序库，并产生更适合机器消耗的输出，例如目标计算机可执行文件、用于目标计算机编程语言运行时间的可链接或可加载计算机程序库或者目标计算机编程语言的源代码。

文档生成器：“文档生成器”是以例如超文本标记语言(HTML)、PDF或POSTSCRIPT等数据格式产生人类可读文档的计算机程序。文档生成器通过解构、交叉编索引及重新排列来自各种来源的文本段落来产生文档。此类源(本文中也称为“文档输入”)可包含：以计算机编程语言编写的源代码文件；例如markdown或HTML等格式的文档输入文件；可从中导出图形、图表及其他非文本内容的媒体文件，其包含例如PNG及JPEG等二进制图像格式连同图像的文本描述，如SVG及DOT；文档元数据文件，其提供帮助将内容组织成分组(如章节)的提示并解释如何找到并链接到跨组织边界的文件，如从另一项目生成的文档，所述文档解释文档软件所使用的概念；解释文档应如何显示的样式文件，其包含可控制文本的颜色及字体大小的级联样式表单(CSS)以及定义使用特定字体再现的每一字母的形状(字形)的印刷字体文件。

被中断散文：术语“被中断散文”或“被中断文本”可以指如下文本段落：如果文本段落中所含有的所有不清晰片段被替换为上下文有效的清晰结构化文本或散文，则所述文本段落将是散文。

库：“库”可被定义为一个或多个算法以可自动化形式的表达式。可自动化形式的示例可以是编程语言代码或其经编译版本(例如，作为字节码、二进制可执行代码等)。通常，当作为一个或多个过程执行时，库并不“拥有”作为其一部分执行的过程。相反，库与更大系统一起执行，或者作为更大系统的一部分执行，所述更大系统将特定种类的算法任务委托给所述库。举例来说，计算机网络上的微服务可被视为库。微服务通常针对其他网络节点存在以删除特定算法任务。

散文：术语“散文”是指主要供人类交流的人类语言文本，而不是以编程语言编写的程序。

运行时间：编程语言的“运行时间”囊括支持执行以那种语言编写的计算机程序的计算机制。举例来说，编程语言的运行时间可囊括理解那种语言的计算机程序被编译成的字节码指令的虚拟机。JAVA虚拟机(JVM)只是此类运行时间的一个示例。另外，本文有时使用术语“运行时间”或短语“在运行时间”来指代计算机程序被执行的时间。

源代码：术语“源代码”可以指囊括以计算机编程语言表达的语句、表达式及命令的结构化文本。

结构化文本：术语“结构化文本”可以指机器可解释且未经特殊培训的人可能难以理解的文本。举例来说，在文本“Use{@link MyClass#method(int,int)}to do XYZ”中，大括号之间的文本是根据需要人类具备专业知识才能解码的标点符号密集的微语言来结构化的。

目标：“目标”可被定义为由客户端用来连接到编译器输出的机制。编程语言可以是目标；程序员编写代码来连接到加载到同一存储器空间中的库。虚拟机(VM)可以是目标；程序员可编写代码，代码被编译为虚拟机运行的字节码种类并依赖于VM经由接口链接使用。另一程序可以是客户端。因此，程序间机制是目标；代码可使用过程间通信(IPC)、远程程序叫用(RPC)或RESTful网络协议将消息发送给在客户端程序的过程之外运行的某个程序(例如网络服务或微服务)，并辨识传入消息何时含有响应。

总体概述

本文中所公开的计算机实施的技术解决了从以通用规范编程语言编写的通用规范为许多编程语言产生惯用软件文档的若干问题。所述技术可由文档生成器计算机程序采用，所述文档生成器计算机程序将所述通用规范翻译成用于许多不同编程语言目标中的每一者的软件编程接口文档。所述技术还可由源到源编译器采用，所述源到源编译器除了将所述通用规范编译成所述不同目标语言以外还并入有从所述通用规范为许多不同编程语言目标中的每一者生成文档的技术。

本文所公开的由技术解决的一个问题是软件编程接口文档不仅仅是散文。举例来说，文档可含有源代码示例。当从通用规范生成用于许多不同目标编程语言的软件编程接口文档时，不同的多组文档应包含从通用规范翻译成用于不同编程语言目标的源代码片段的源代码片段。

一个相关问题是文档可具有由程序员与散文内联编写的嵌入式结构化文本。举例来说，考虑了含有与散文内联的嵌入式结构化文本的以下示例性多行源代码注释块：

01:/**

02:*小心不要过度拧紧螺栓！这样做可能会导致结构上的失效

03:*元素！默认情况下，BoltTightener拧紧到[inline

04:*DEFAULT_MAX_TORQUE_VALUE].如果这个值太高，请使用{@link

05:*BoltTightener.setMaxTorque()}拧紧**之前**。

06:*/

在此示例性注释块中，句法“/**”及“*/”用于指示注释块的开始及结束，嵌入式结构化文本是字符串“[inline DEFAULT_MAX_TORQUE_VALUE]”及字符串“{@linkBoltTightener.setMaxTorque()}”。程序员可期望编译器或文档生成器将嵌入式结构化文本替换为链接或其他丰富或特殊格式化内容。在当前示例中，程序员可期望编译器或文档生成器将嵌入式结构化文本“[inline DEFAULT_MAX_TORQUE_VALUE]”替换为命名为“DEFAULT_MAX_TORQUE_VALUE”的变量的通用规范的编程语言中的声明的初始值。另外，程序员可期望编译器或文档生成器将嵌入式结构化文本“{@linkBoltTightener.setMaxTorque()}”替换为文档间超链接。程序员可期望编译器或文档生成器的其他功能。举例来说，在公制用户的文档的版本中，程序员可期望将扭矩值翻译为牛顿米。所生成文档如果不满足程序员的期望，将会使程序员感到沮丧，并且相关联软件可会被认为是低质量的。

针对许多不同编程语言目标解决的另一问题是满足编程语言社区对文档的不同期望。针对不同编程语言的不同文档生成器的非详尽列表包含：用于D的DDOC、用于KOTLIN的DOKKA、用于C++的DOXYGEN、用于JAVA的JAVADOC、用于JAVASCRIPT的JDOC、用于OCAML的OCAMLDOC、用于PERL的PERLDOC、用于PHP的PHPDOCUMENTOR、用于PYTHON的PYDOC及用于SCALA的SCALADOC。这些不同社区的程序员投入了时间学习如何有效地扫描由这些文档生成器产生的文档。软件编程语言文档在风格及组织上与由编程语言社区首选文档生成器产生的文档有太大差异，这将被认为不必要地难以消化且质量较低。

针对许多不同编程语言目标解决的又一个问题是满足机器的期望(例如，在接受软件编程接口文档作为输入的计算机装置上执行的计算机程序)。在计算装置上执行的集成开发环境(IDE)就是此种机器的一个示例。举例来说，当使用IDE的程序员移动源代码中字词的点装置光标时，IDE可显示与那个字词相关的所生成文档的片段。作为另一示例，当程序员开始键入源代码字词时，IDE可建议所述字词的前缀的可能补全连同每一可能补全的相关联文档片段。举例来说，考虑了将“isRe”键入到IDE源代码编辑器中的程序员。作为响应，IDE可提供以下选项作为可能补全：

●“isReadable–如果其已发布并且可供阅读则为真”。

●“isReady–如果将通过发布前检查则为真”。

与上述问题相关的是，如果IDE无法使用其可能利用通常所使用的文档生成器的输出开发及测试的算法来提取相关文档片段，则与那个文档绑定在一起的软件库将更难学习并且更难正确使用。

已解决的又一个问题是支持文档中的交叉引用。返回到上述螺栓紧固器示例，回想注释块包含引用程序元素的嵌入式结构化数据。所述程序元素在注释块中用文本“{@link BoltTightener.setMaxTorque()}”来引用。此种结构化数据可被转换成超链接。当转换为超链接时，需要将引用翻译为机器可解释引用。机器可解释引用的示例是链接到解释所述引用的所生成文档的另一部分的统一资源定位符(URL)。另外，当转换为超链接时，嵌入式结构化文本需要替换为“链接文本”。对于不同编程语言目标，链接文本通常会有所不同。举例来说，C++程序员在注释块中引用命名为“setMaxTorque”的概念实体的方式可能与PYTHON程序员在注释块中引用那个实体的方式不同。

已解决的又一个问题是目标编程语言中的规范中的公共软件编程语言接口元素可能与通用规范编程语言中的通用规范中的元素不一对一对应。特定来说，通用规范可定义与目标编程语言的规范中的任何单个元素不对应的元素的概念分组。举例来说，考虑了通用规范编程语言中基本方向概念的以下定义：

上述定义定义了命名为“CardinalDirection”的概念分组，并为概念分组内的四个相异实体进行了命名。一些目标编程语言可能不会以同一方式定义概念分组。这样一来，并不总是存在对通用规范中的概念分组的文档交叉引用到对如目标编程语言中所定义的概念分组的文档交叉引用的一对一翻译。

举例来说，概念分组可以PERL编程语言来定义，如下所示：

此处，概念分组是根据广泛接受的PERL编程实践来定义的，其中概念实体名称是概念分组内每一实体名称的前缀并呈所展示的大写及下划线形式。然而，作为结果，不存在“CardinalDirection”可引用的编程语言构造。

作为另一示例，概念分组可以GO编程语言来定义，如下所示：

此处，对CardinalDirection的交叉引用可翻译为“type CardinalDirection”。然而，按惯例，GO程序员通常将那个定义放在其自身源代码文件中，并在文档交叉引用中引用所述文件而不是类型定义本身。

并且概念分组可以JAVA编程语言来定义，如下所示：

与上述PERL及GO示例不同，在JAVA示例中，有可能将文档交叉引用直接翻译为“CardinalDirection”。

又一个问题是，由程序员在通用规范中的源代码注释中编写的用法示例可引用在不同目标语言中以不同方式表示的通用概念。此类用法示例通常遵循以下叙述弧：

1.连接到库。

2.创建一些输入。

3.将库的部分内容与输入一起使用。

4.对于输出进行解释。

考虑以下可能在通用规范中定义的用法示例：

01:import documentedLibrary；

02:let independenceDay＝Date(year:1776,month:8,day:2)；

03:let dayCount＝documentedLibrary.daysSince(independenceDay)；

04:/*dayCount is a number.Approximately 89,000*/

此处，日期是通用概念。第01行连接到库。第02行创建输入。第03行使用所连接库的一部分作为输入。第04行是解释输出的注释。这个用法示例及其他类似用法示例应按目标编程语言以不同方式翻译成熟悉目标语言的程序员将辨识为表达日期通用概念的示例的用法示例。举例来说，JAVA中的用法示例应可能将来自通用规范的短语“Date(year:1776,month:8,day:2)”替换为基于java.time包的文本。并且在传统上将日期表示为遵循某些约定的字符串的目标编程语言中，作为实例，日期短语可被替换为字符串“17760802”。

又一个问题是，文档交叉引用可横跨通用规范。举例来说，两个不同通用规范可由不同程序员团队分别维护。尽管如此，通用规范中的一者可含有对另一通用规范的文档交叉引用。应在目标编程语言文档中维护这种交叉引用，以便从通用规范生成。

本文中所公开的技术解决了所有这些问题，由此提供了对用于从通用规范为许多编程语言产生惯用软件文档的计算机实施的技术的现有技术的改进。

文档生成系统

图1是用于从通用规范为许多编程语言产生惯用软件文档的软件文档生成系统的示意图。对系统的输入102包含通用规范104。通用规范104可囊括至少两种类型的可打印文本内容：(1)以通用规范编程语言编程的编程语言语句及表达式(源代码)；以及(2)源代码注释(文档片段)。注释可包含散文、嵌入式结构化文本及源代码用法示例。

通用规范104可作为一个或多个文件或者一个或多个其他适合数据容器存储在计算机存储介质中。一个或多个数据容器可囊括含有源代码的一个或多个数据容器，所述源代码还可含有源代码注释。然而，含有源代码的数据容器还可能含有对含有源代码的源代码注释的另一数据容器的引用或链接(例如，超链接)。这样一来，虽然源代码及源代码注释可存储在同一数据容器中，但其可替代地存储在单独数据容器中，其中文本链接或引用用于从源代码数据容器内引用源代码注释数据容器。

举例来说，考虑了通用规范104的以下可能片段。第01行到第0806囊括一个文档片段。第01行处的字符序列“/**”指示文档片段的开始。第0806行的字符序列“/**”指示文档片段的结束。第02行是散文。第03行到第0705行指示围封在类似XML的标记<example></example>内的用法示例。并且第0907行表示非文档编程语言指令源代码，其中“...”用于表示示例中未提供的进一步细节，以便提供清晰示例。

虽然在上述示例中，类似XML的标记用于将注释块的一部分指定为囊括用法示例，但在其他实施方式中使用其他语法。举例来说，作为一种可能性，可将用法示例围封在单独行上的两个反引号“``”内，而不是类似XML的标记。

通用规范104可被输入到文档片段提取器106及编译器118两者。文档片段提取器106可从通用规范104或者由通用规范104引用的一个或多个文件提取文档片段，并且编译器118可从通用规范104提取源代码。此种提取可涉及由编译器前端执行的操作，例如行重构、预处理、词法分析(令牌化)、语法分析(解析)及语义分析。一般来说，从通用规范104提取的文档片段可对应于通用规范104中的源代码注释，并且从通用规范104提取的源代码可对应于通用规范的不是注释的其他文本。其他文本可囊括通用规范编程语言中的语句及表达式。

虽然在一些实施方式中，文档片段中的一些或全部与通用规范104的源代码文件中的源代码内联地被包含，但文档片段中的一些或全部是从与通用规范104的源代码文件中的源代码内联的文本链接(例如，超链接)引用的文件获得的。因此，文档片段中的全部可从含有源编程语言中的源代码的通用规范104的源代码文件提取，文档片段中的全部可从由通用规范104的源代码文件中的文本链接引用的单独文件提取，或者文档片段中的一些可从通用规范104的源代码文件提取，并且文档片段中的一些可从由通用规范104的源代码文件中的文本链接引用的单独文件提取。从通用规范104提取文档片段可囊括这些类型的提取中的任一者。

编译器118还可对通用规范104的源代码的中间表示执行操作。中间表示可由编译器118生成作为对通用规范104的源代码执行的前端操作的结果。在一些实施方式中，中间表示是基于如于2020年12月33日提交的标题为“派生许多惯用编程语言接口(DerivingMany Idiomatic Programming Language Interfaces)”的相关美国专利申请号17/131,574中所描述的一组语际定义元素，所述专利申请案的全部内容由此以引用的方式并入。

编译器118可对中间表示执行各种操作。编译器118可对中间表示执行的一些分析操作可包含数据流分析、依赖性分析、别名分析、指针分析、转义分析或者可由编译器中端执行的其他适合分析操作。编译器118可对中间表示执行的一些优化操作可包含内联扩展、死代码消除、常量传播、循环变换或可由编译器中端执行的其他适合优化操作。

编译器118的输出可被输入到代码生成器120。代码生成器120对应于特定编程语言目标的编译器后端。系统可囊括用于许多不同编程语言目标的许多代码生成器。在图1的示例中，为了简单起见，仅展示一个代码生成器120。在一些实现方案中，系统囊括用于许多不同编程语言目标的许多代码生成器。举例来说，系统可囊括以下编程语言目标中的每一者的相异代码生成器：C、JAVA、PYTHON、C++、C#、JAVASCRIPT、PHP、SWIFT、R、LISP、FORTRAN、ADA、PASCAL、GROOVY、RUBY、GO、OBJECTIVE-C、DART、SCALA及LUA。

文档片段语言

由文档片段提取器106从通用规范104提取的文档片段的源代码用法示例可符合文档片段编程语言。文档片段语言可以是通用规范编程语言、通用规范编程语言的子集或者专门用于授权文档中的源代码用法示例的编程语言。

文档片段语言可提供用于编写源代码用法示例作为通用规范104中的源代码注释的一部分的各种能力。文档片段语言可允许规定一序列步骤。举例来说，在以下示例中，存在序列中的三个步骤：第一步骤位于第01行处，下一步骤位于第02行处，并且最后一步骤位于第03行处：

01:import documentedLibrary；

02:let independenceDay＝Date(year:1776,month:8,day:2)；

03:let dayCount＝documentedLibrary.daysSince(independenceDay)；

文档片段语言可允许变量名称的声明。举例来说，在上述第02行中，关键字词“let”用于声明变量名称“independenceDay”。

文档片段语言可允许经由通用概念语料库112来精心制作一个值。举例来说，在上述第02行中，表示1776年8月2日的值Date(year:1776,month:8,day:2)是经由通用概念语料库112来精心制作的。

文档片段语言可允许值与变量名称相关联。举例来说，在上述第02行中，相等符号(‘＝’)用于将经由通用概念语料库112来精心制作的值与变量名称“independenceDay”相关联。

文档片段语言可允许使用文档库的应用编程接口的一部分以及名称或值来获得值作为结果。举例来说，在上述第03行中，命名为“documentedLibrary”的库的接口与变量名称“independenceDay”搭配使用以获得与变量名称“dayCount”相关联的值作为结果。

文档片段语言可支持足以区分要使用哪个接口元素的交叉引用语法。举例来说，在上述第03行中，句点('.')用于将库名称“documentedLibrary”与接口元素“daysSince”区分开。

文档片段语言可支持程序叫用语法，允许对要在程序叫用中发送(传送)的值进行分组。举例来说，在上述第03行中，接口元素名称“daysSince”后面的左括号及右括号用于规定要在程序叫用中传送的值。

文档片段语言可支持以散文形式解释某些步骤的作用。举例来说，文档片段语言可支持间质编程语言注释，例如“/*some prose*/”。

文档片段语言可支持结构化编程语言语句的使用，例如if-then-else以及for及while循环语句，以允许程序员在源代码用法示例中展示如何组合不同策略。

文档片段语言可支持对值的进一步讨论的任何结果的识别。作为示例：文档片段语言可提供允许程序员展示结果等效于值的语法(例如，“result＝＝42”)。文档片段语言可允许使用习惯用语连同散文来展示，如果读者运行由源代码用法示例表示的程序(例如，“print(result)/*would print 42*/”)，则读者将看到什么。文档片段语言可允许使用元数据来规定，如果读者运行其中元数据被格式化以使读者清楚与元数据相关联的文本规定如果读者运行程序读者将看到什么的程序，则读者将看到什么。举例来说，文本‘//stdout:“Hello,World！”’可用于规定文本“Hello,Word！”将输出到程序的标准输出装置，且其中文本“//stdout:”是用于规定如此的元数据。

文档片段语言可允许表达出现在另一程序内部的嵌套式程序。

语句与表达式之间的区别

许多编程语言目标对语句与表达式进行区分。语句是源代码的单元，其规定要实行的某些动作。语句的示例包含断言语句、赋值语句、goto语句、return语句、call语句、block语句、do-loop语句、for-loop语句、if-then-else语句、switch语句、while-loop语句、with-语句等。表达式是源代码的单元，其经评估以确定其值。在许多情形中，语句可含有表达式，但表达式未含有语句。嵌套式程序是例外。总之，表达式创建值并可能产生副作用，而语句的唯一目的是产生副作用。

某些编程语言并不区分语句与表达式。举例来说，某些函数式编程语言不进行这种区分。有可能将不在语句与表达式之间进行区分的编程语言的源代码翻译为在语句与表达式之间进行区分的另一编程语言的源代码。这样做通常涉及引入临时(一次性)变量。此类变量用于临时保存值，但通常使用对人类没有意义的变量名称。因此，引入临时变量来将源代码用法示例翻译成旨在阅读的目标编程语言的源代码用法示例将导致低质量的文档。因此，文档片段语言可在表达式与语句之间进行区分，包含具有关于每一种类可在通用规范104中的源代码用法示例中的何处使用的规则。这样，通用规范104中的源代码用法示例可被翻译为在不使用具有无意义名称的临时变量的情况下也支持这种区别的目标编程语言中的源代码用法示例。

嵌套式程序

某些目标编程语言不准许嵌套式程序。嵌套式程序是在另一程序中定义的程序。为了支持到确实准许嵌套式程序的目标编程语言及不允许嵌套式程序的目标编程语言的翻译，文档片段语言可要求给予嵌套式程序一个描述性名称，即使在通用规范104中的源代码用法示例中没有提及所述名称。通过这样做，对于不支持嵌套式程序的目标编程语言，可将嵌套式程序转换成可通过给定描述性名称叫用的目标语言中的非嵌套式程序。举例来说，可例如通过使用元数据在通用规范104中的源代码用法示例中明确提及描述性名称。替代地，在检测到通用规范104中的未命名嵌套式程序之后，可即刻提示用户进行用户输入以提供描述性名称。

通用概念语料库

可在系统中提供通用概念语料库112，用于将从通用规范104提取的文档片段中的短语翻译为给定目标编程语言的等效短语的外部概念。举例来说，对于JAVASCRIPT，通用概念语料库112可将来自上述示例的“Date(year:1776,month:8,day:2)”翻译为用于JAVASCRIPT的“new Date(1776,7,2)”。

通用概念语料库112可以被实施为抽象令牌的翻译器。举例来说，可使用基于机器学习或语法驱动的翻译器。举例来说，通用概念语料库112可从“Date(year:1776,month:8,day:2)”产生以下抽象令牌序列：

01:<concept><common:Date></concept>

02:<year>1776</year>

03:<month>8</month>

04:<day>2</day>

上文示例的抽象令牌序列被格式化为类似可扩展标记语言(XML)。然而，不需要特定抽象令牌序列格式，并且类似XML的格式仅仅用作一种可能格式的示例。其他结构化文本格式或二进制格式也是可能的。

通用概念语料库112可使用语法驱动翻译器将从通用规范104提取的文档片段中的通用概念的抽象令牌序列形式翻译为目标语言的令牌序列。举例来说，通用概念语料库112可囊括用于每种目标编程语言及每一概念的翻译语法。举例来说，JAVASCRIPT的翻译语法及日期概念可能如下所示，以增强型巴科斯诺尔范式(ABNF)(Augmented Backus-NaurForm(ABNF))表达：

作为另一示例，JAVA的翻译语法以及日期概念可能如下所示，同样以ABNF表达：

在上述示例性语法中，带引号的令牌以未经改变的方式包含在输出中。输入时需要尖括号“<...>”之间的令牌，除非标有“postprocess:”以用于后处理传送期间的处理。“/.../”之间的语法内容使用正则表达式语法来匹配不在尖括号之间的输入令牌。

为了演练示例，请考虑可能位于从通用规范104提取的文档片段中的以下示例性源代码用法示例：

然后，通用概念文本“Date(year:1776,month:8,day:2)”可转换为以下抽象令牌序列：

01:<concept><common:Date></concept>

02:<year>1776</year>

03:<month>8</month>

04:<day>2</day>

然后，如果将日期概念的示例性JAVASCRIPT语法应用于上述抽象令牌序列，则会生成JAVASCRIPT语言的以下抽象令牌序列：

01:<concept><common:Date></concept>

02:“new”

03:“Date”

04:“(“

05:<year>“1776”</year>

06:“,”

07:<month>8</month>

08:“,”

09:<day>2</day>

10:“)”

最后，在移除尖括号令牌并根据JAVASCRIPT约定插入空格之后，从上述抽象令牌序列生成以下JAVASCRIPT源代码：

01:new Date(1776,8,2)

后处理

有时，翻译的一部分需要将片段添加到程序的另一部分。举例来说，在使用术语“DateTime”来引用JAVA的核心java.time包中的类型之前，JAVA编程语言需要像“importjava.time.LocalDate；”一样的导入指令，靠近源文件的顶部。为了支持此种使用，目标语言的翻译语法可包含提升指令。提升指令向后处理传送发出信号，以将相关联语句移动到源文件中的适当位置。举例来说，上面用于日期概念的JAVA语法将从表示通用概念文本“Date(year:1776,month:8,day:2)”的初始抽象令牌序列生成以下抽象令牌序列：

01:<postprocess:hoist to＝"java:imports">

02:import java.time.LocalDateTime；

03:</postprocess:hoist>

04:<postprocess:hoist to＝"java:imports">

05:import java.time.Month；

06:</postprocess:hoist>

07:LocalDate.of(1776,Month.AUGUST,2)

在上述示例中，第01行到第06行含有用于后处理传送的提升指令，以将第02行及第05行处的相关联导入语句移动(提升)到源代码文件中用于含有JAVA导入语句的适当位置(例如，靠近源代码文件的顶部)。

信封

一些源代码用法示例略去了非必要细节。举例来说，源代码用法示例的编写者可能会假设读者将知道如何在所提供用法示例的上方及下方添加通用样板文件，以将其变成完整程序。这种样板文件在本文中被称为源代码用法示例的“信封”。被翻译为目标编程语言中的源代码用法示例的通用规范104中的源代码用法示例的信封是源代码用法示例的所显示部分之前及之后的内容，其对于源代码运行是必要的，但如果对读者可见，则将分散编写者试图阐述的观点。

在一些实施方式中，所生成文档包含信封但以不可见的方式进行设计。另外，当对源代码用法示例的可见部分应用“复制到剪贴板”操作或“在源代码编辑器中打开”操作时，信封被包含在内。

通用规范104中的源代码用法示例到目标编程语言的翻译可包含抽象令牌以将信封内容与相关内容区分开。抽象令牌可对信封内容的开始及结束进行标记。举例来说，仅对上述所讨论的通用日期概念进行JAVA翻译，但在对上述所讨论的提升指令进行后处理之后，可能会具有信封内容：

01://BEGIN ENVELOPE

02:package com.example；

03:import java.time.LocalDate；

04:import java.time.Month；

05:public class C{

06:public static void main(String[]argv){

07://END ENVELOPE

08:LocalDate.of(1776,Month.AUGUST,2)

09://BEGIN ENVELOPE

10:；

11:}

12:}

13://END ENVELOPE

在上述示例中，文本“//BEGIN ENVELOPE”及文本“//END ENVELOPE”是用于构成信封内容的开头及结尾的抽象令牌。

信封还有其他用途。举例来说，当源代码用法示例翻译产生目标语言中的独立程序时，可编译并执行所述程序以确定其是否产生错误。这提供了简易方法来检测翻译中的错误以及编写者的错误假设。

此外，源代码用法示例中或邻近源代码用法示例的结构化文本可指示所述示例的预期输出。可编译并执行具有信封的源代码用法示例到目标语言的翻译，以测试程序的输出是否与预期输出匹配。请注意，预期输出可能是错误或引发异常，例如当提供源代码用法示例以说明如何不进行编程时。在此情形中，可执行所述程序来测试其是否生成预期错误代码或抛出预期异常。

信封可例如按目标编程语言来单独规定。替代地，信封可由文档片段翻译器114自动生成及输出。

信封及测试示例

返回到先前示例，考虑了通用规范104的以下可能内容：

文档片段提取器106可通过开始“/**”及结束“*/”注释块标记来将第01行到第0806行识别为源代码注释块。基于这个识别，文档片段提取器106可提取第02行到第-705行作为文档片段。同时，编译器118可将第0907行识别为未围封为通用块的一部分并且要被编译的源代码。文档片段提取器106可将所提取文档片段传送到文档片段翻译器114上。

本示例中的文档片段含有上述通用规范104示例的第0403行及第0504行处的源代码用法示例。当文档片段含有源代码用法示例时，文档片段翻译器114可被配置为将源代码用法示例翻译为特定目标编程语言中的经包封源代码用法示例。然后可将经包封源代码用法示例输出到测试源代码文件124。举例来说，对于当前示例，如果目标语言是JAVA，则测试源代码文件124可含有以下JAVA源代码：

在这个示例中，JAVA源代码的第05行及第06行直接派生自上述通用规范104示例的第0403行及第0504行。JAVA源代码的剩余行是由文档片段翻译器114自动生成的信封的一部分。

本示例中的文档片段含有通用规范104示例的第0605行处的预期输出指示符“//stdout:”。当文档片段含有预期输出指示符时，文档片段翻译器114可被配置为将预期输出输出到预期输出文件122，预期输出文件122可以是文件系统文件或标准输出“file”。举例来说，对于当前示例，预期输出文件122可含有以下内容：

01:Hello,World！

编译器118可将通用规范104中的源代码的中间表示(例如，抽象令牌序列)传送到代码生成器120上。另外，文档片段翻译器114可将文档片段的中间表示(例如，抽象令牌序列)传送到代码生成器120上。代码生成器102可针对特定目标语言(例如，JAVA)。代码生成器102从输入中间表示产生目标语言中的库源代码文件126。库源代码文件126含有通用规范104中的源代码到目标语言的翻译以及文档片段到目标语言的翻译两者。举例来说，对于当前示例，如果目标语言是JAVA，则库源代码文件126可含有以下内容：

在上述示例中，第01行到第03行以及第20行到第21行表示通用规范104示例的源代码的JAVA翻译，并且第04行及第19行表示文档片段示例的JAVA翻译。应注意，JAVA文档片段含有从通用规范104示例提取的文档片段的源代码用法示例的翻译。源代码用法示例的JAVA翻译包含由类似XML的标记描绘的信封。如果<span>标签被处理为超文本标记语言(HTML)等等，则级联样式表单(CSS)等等中的“envelope”类的定义可用于在图形用户接口(例如通过源代码编辑器、web浏览器或其他计算机应用)中的库源代码文件126的默认呈现中隐藏信封的内容。举例来说，默认情况下，库源代码文件126的内容可被显示出来，而信封内容不可见，如下所示：

目标语言编译器130可将库源代码文件126编译成目标库138。举例来说，如果目标是JAVA，则目标语言编译器130可以是常规或第三方JAVA源代码编译器。

目标语言文档生成器134可从库源代码文件126生成目标文档140。举例来说，如果目标是JAVA，则目标语言文档生成器134可生成用于计算机程序等等的JAVADOC。

测试运行器128可使用目标语言编译器130将测试源代码文件124编译成可运行计算机程序。然后，测试运行器128可运行计算机程序并捕获输出以与预期输出122进行比较。当运行时，测试计算机程序可加载并调用从库源代码126生成的目标库138。如果由测试运行器128捕获的测试计算机程序的输出与预期输出122不匹配，则测试运行器128可指示测试失败测试结果数据136。此种测试结果可指示在通用规范104中编写的源代码用法示例含有漏洞或其他编程错误，或者可指示文档片段翻译器114在将源代码用法示例翻译为目标语言时存在问题。另一方面，如果由测试运行器128捕获的测试计算机程序的输出与预期输出122匹配，则测试运行器128可指示测试结果数据136的测试成功。

包含测试结果136、目标语言库138及目标语言文档140的系统的输出134可存储在一个或多个计算机存储介质中。

系统可包含其他文档片段翻译器114、其他代码生成器120、其他目标语言编译器130以及用于其他目标语言的其他目标语言文档生成器132。以这种方式，系统可从通用规范104为许多编程语言目标生成惯用软件文档。共享组件108包含外部交叉索引获取器110，并且通用概念语料库112可在系统内跨许多不同编程语言目标而共享。

文档片段翻译器

文档片段翻译器114可被配置为将从通用规范104提取的文档片段翻译为对于熟悉特定目标编程语言的程序员有意义的格式。文档片段翻译器114的输出可被嵌入于用于目标编程语言的源代码126中。然后源代码可被输入到目标语言文档生成器132以生成源代码126的文档140。替代地，文档片段翻译器114可绕过目标语言文档片段翻译器114并且以不需要目标编程语言特定工具来生成的特定格式(如HTML或PDF等等)直接输出文档140。

从通用规范104提取的文档片段可包含被中断散文、文档片段语言中的源代码用法示例或者交叉引用。除了要翻译的文档片段以外，文档片段翻译器114还可接收额外输入。特定来说，文档片段翻译器114可接收与通用规范104中所定义的引用相关的交叉索引116，为通用规范104生成文档140到从通用规范104派生的目标库138中明显的引用。交叉索引116还可包含从其他通用规范派生的库的交叉索引，其中此类交叉索引可定义由文档片段翻译器114为其生成文档140的通用规范104所使用的输入、输出或运算符。

到文档片段翻译器114的其他输入可包含：允许文档片段翻译器114使用外部交叉索引获取器110来获取其需要的交叉索引的元数据；描述文档140将在何处(例如由URL规定的网络位置)可用或发布的元数据；描述输入文档片段中散文的语言环境或人类语言的元数据；描述文档140的读者偏好的语言环境或人类语言的元数据；描述文档片段的源代码用法示例是否是有效示例或旨在解释不该做什么的元数据；描述文档片段的源代码用法示例的计算结果的元数据；或者描述基于所翻译源代码用法示例及适合信封来运行测试计算机程序的人应看到的内容的元数据。

文档片段翻译器114可被配置为将从通用规范104提取的文档片段中的散文从一种人类语言翻译为另一人类语言，使得输出库源代码文件126包含目标人类语言的散文。

文档片段翻译器114可将文档片段语言的源代码用法示例翻译成目标语言中的等效源代码用法示例。这样做时，文档片段翻译器114可为目标语言中的等效源代码用法示例生成并引入目标编程语言中的信封。

文档片段翻译器114可产生额外输出，以使得能够对照测试计算机程序的实际结果或实际输出来检查源代码用法示例的任何预期结果或预期输出，所述测试计算机程序是从目标语言的源代码用法示例的经包封版本编译的，且然后运行以生成实际结果或实际输出。另外或替代地，文档片段翻译器114可在内部执行质量控制检查并发出其结果作为额外输出。

翻译阶段

现参考图2，文档片段翻译器114可使用应用于从通用规范104提取的文档片段的解析器。解析器可用于分离出被中断文本内的结构化文本。元素242描绘从通用规范提取的示例性文档片段，所述通用规范含有具有嵌入式结构化文本的被中断散文。在元素242中，嵌入式结构化文本是斜体的。

文档片段翻译器114然后可将被中断散文分离，但指示在何处从与被中断散文隔离的结构化文本部分(例如，如在元素246中)重新并入结构化文本(例如，如在元素244中)的结构化文本占位符。元素244展示元素242的被中断散文，但具有指示在何处重新并入结构文本的结构化文本占位符。元素246使占位符与所分离结构化文本相关。

作为文档片段翻译器114使用解析器将被中断散文与其嵌入式结构化文本分离的替代，文档片段翻译器114可从文档片段提取器106接收经预分离的这些成分。举例来说，代替文档片段提取器106将如元素242的所组合形式的文档片段输入到文档片段翻译器114，文档片段提取器106可输入如元素244及246的文档片段的经预分离形式。

文档片段翻译器114可将具有嵌入式占位符的被中断散文翻译为具有嵌入式占位符的所翻译被中断散文。这样做时，不需要翻译占位符文本。举例来说，元素248表示元素244的英语被中断散文的西班牙语翻译。请注意，元素248的所翻译被中断散文仍含有位于同一语义位置中的占位符。

翻译例如元素246的“cross_reference_2”等的交叉索引短语可涉及文档片段翻译器114在交叉索引表中查找短语的全部或部分。在通用规范104的编译期间构建这些表可能是方便的，因为编译器118可能已经在较大程序内找到并处理了所命名实体，并且当缩写名称与上下文中的较长独立名称相同时使用了用于识别其规则。编译器118还可频繁地处理引用由第三方编写的源文件中定义的编程语言结构的名称，因此编译器118通常方便地产生交叉索引，所述交叉索引允许将交叉索引短语与由通用规范104引用但在通用规范104外部定义的编程语言元素相关。

元素246含有对由元素242表示的文档片段的源代码用法示例的引用“code_sample_1”。在元素250中，源代码用法示例已被翻译为目标语言的经包封源代码用法示例。而且，在元素250中，“cross_reference_2”值#Rainbow已被翻译为特定对应URL。然后，文档片段翻译器114将所翻译被中断散文与由元素248表示的嵌入式占位符以及翻译为由元素250表示的结构化文本的相关占位符重新组合为清晰的半结构化文本，其具有对端用户工具有意义的格式化提示，如由元素252所表示。此类端用户工具可包含目标语言编译器130、目标语言文档生成器132以及用于查看所生成文档140的工具(例如，web浏览器、IDE或源代码编辑器)。

在元素242中，斜体文本表示嵌入式结构化文本。在元素244中，斜体文本表示嵌入式占位符文本。在元素248、246中，斜体文本表示嵌入式结构化文本。在元素252中，斜体文本表示具有对端用户工具有意义的格式提示的半结构化文本。

文档生成过程

图3是用于从通用规范为许多编程语言目标产生惯用软件文档的过程的流程图。操作354及356可针对许多编程语言目标来执行一次。操作358到372可针对每一编程语言目标来执行。

在操作354处，从通用规范提取的文档片段的源代码用法示例的文本可用元数据来扩充。文本可基于编译器对文本上的文档片段语言的一个或多个传送来扩充，以添加可在文本中提及但通常为了简洁而被省略的隐式构造。举例来说，文本“let n＝123；”源代码用法示例可用数据类型信息来扩充，例如如“let n:number＝123；”，其中文本“:number”扩充变量“n”以指示其表示数字数据类型而不是字符串、用户定义的数据类型或其他数据类型。其他基于编译器的扩充也是可能的，并且不需要特定的一组扩充。

在操作356处，扩充文本被转换成以独立于任何特定目标编程语言的中间形式表示经扩充文本的第一抽象令牌序列。所述转换可根据机器学习过程或语法驱动过程来进行。用于将扩充文本转换成可用作第一抽象令牌序列的语际定义元素序列的语法驱动方法在2020年12月22日提交的标题为“派生许多惯用编程语言接口(Deriving Many IdiomaticProgramming Language Interfaces)”的相关美国专利申请号17/131,574中描述，其全部内容由此以引用的方式并入。

在操作358处，针对给定目标语言对第一抽象令牌序列进行预处理。举例来说，如果目标语言不支持嵌套式函数，而源代码用法示例涉及嵌套式函数，则可执行闭包转换。

在操作360处，用于给定目标语言的文档片段翻译器是从文档片段翻译器的语料库选择的。

在操作362处，将所选择文档片段翻译器应用于第一抽象令牌序列以生成在结构上更接近给定目标语言的第二抽象令牌序列。翻译可以是基于机器学习的或语法驱动的。

在操作364处，对第二抽象令牌序列执行后处理。举例来说，当第二序列中的一系列令牌被指示其是交叉引用的标记围绕时，接着可执行交叉引用变换并且将变换应用于第二序列以替换第二序列中的该系列令牌。作为另一示例，当第二序列中的一系列令牌被指示该系列令牌需要被提升的标记围绕时，接着将该系列令牌移动到其在第二序列中的所规定目的地，所述目的地可在信封中。

在操作366处，第二序列中不必要的令牌被移除。此类不必要的令牌可包含不贡献文本或识别需要在翻译中持续的边界的令牌，例如信封边界。

在操作368处，将目标特定的源代码格式化器应用于随后的第二抽象令牌序列，以在读者期望人们放置空格的地方插入空格。对于大多数目标，其可足以：

1.查找非文本输出令牌，例如信封边界标记，并记下其序号位置，

2.连接文本令牌，每一令牌之间具有单个空格，

3.使用适合于给定目标语言的代码格式化程序(例如高档打印机)来格式化经连接文本，

4.使用适合于给定目标语言的词法分析器将经格式化文本分裂为包含空格令牌在内的令牌，及

5.在序号位置处重新插入非文本标记，注意不要对所插入空格令牌进行计数。

在操作370处，选择适合于给定目标语言的工具链的嵌入器。举例来说，对于JAVA可选择JAVADOC，并且对于KOTLIN可选择DOKKA，其中两个嵌入器都允许在源代码注释中嵌入HTML。HTML嵌入器将文本令牌转换为显示那个文本内容的HTML短语，并且信封边界被替换为元数据标签，所述元数据标签既向读者隐藏信封内容，又使信封内容可供可使用信封内容的脚本及操作使用。此类操作可包含复制到剪贴板操作或在编辑器中打开操作。

在操作372处，嵌入器被应用于令牌流以产生所翻译文本片段，所述所翻译文本片段可能在由目标特定文档生成器进一步处理之后成为对熟悉目标的人有意义的清晰结构化的文本。

基本计算装置

所述技术可由至少一个计算装置来实施。如果通过不止一个计算装置来实施，则所述技术可使用使用例如分组数据网络的网络耦合在一起的计算装置的组合来整体或部分地实施。在所述技术的实施方式中使用的计算装置可以是硬连线的以执行一些或所有技术，或者可包含数字电子装置，例如被持久编程以执行一些或所有技术的至少一个特殊应用集成电路(ASIC)或场可编程门阵列(FPGA)，或者可包含经编程以根据固件、存储器、其他存储装置或组合中的程序指令执行一些或所有技术的至少一个一般用途硬件处理器。在所述技术的实施方式中使用的计算装置也可将定制硬连线逻辑、ASIC或FPGA与定制编程组合，以实现所述技术中的一些或全部。在所述技术的实施方式中使用的计算装置可以是服务器计算装置、工作站计算装置、个人计算装置、可携式计算装置、手持式计算装置、移动计算装置或者并入有硬连线或程序逻辑来实施所述技术中的一些或全部的任何其他计算装置。

图4是可在所述技术的实施方式中使用的示例性基本计算装置的框图。在图4的示例中，计算装置400及用于实施硬件、软件或硬件与软件的组合中所述技术中的一些或全部的指令被示意性地表示为例如方框及圆圈，其详细程度与本公开所属领域的技术人员通常用于传递关于计算机架构及计算装置实施方式的详细程度相同。

计算装置400包含输入/输出(I/O)子系统402，所述子系统可包含总线或其他通信机制，用于通过电子信号路径在计算装置400的组件之间传递信息或指令。I/O子系统402可包含I/O控制器、存储器控制器及至少一个I/O端口。电子信号路径在图式中示意性地表示为例如线、单向箭头或双向箭头。

至少一个硬件处理器404耦合到I/O子系统402，用于处理信息及指令。硬件处理器404可包含例如一般用途微处理器或微控制器或特殊用途微处理器，诸如嵌入式系统或图形处理单元(GPU)或者数字信号处理器或ARM处理器。处理器404可包括集成算术逻辑单元(ALU)，或者可耦合到单独ALU。

计算装置400包含一个或多个存储器单元406，例如主存储器，其耦合到I/O子系统402，以用于电子数字地存储数据及将由处理器404执行的指令。存储器406可包含易失性存储器，例如各种形式的随机存取存储器(RAM)或其他动态存储装置。存储器406还可用于在由处理器404执行指令期间存储临时变量或其他中间信息。当存储在处理器404可访问的非暂时性存储介质中时，此类指令可使计算装置400成为特殊用途机器，所述特殊用途机器经定制以执行指令中所规定的操作。

计算装置400还包含耦合到I/O子系统402的非易失性存储器，例如只读存储器(ROM)408或其他静态存储装置，用于存储用于处理器404的信息及指令。ROM 408可包含各种形式的可编程ROM(PROM)，例如可擦除PROM(EPROM)或电可擦除PROM(EEPROM)。永久存储装置单元410可包含各种形式的非易失性RAM(NVRAM)，例如FLASH存储器或固态存储装置、磁盘或光盘(例如CD-ROM或DVD-ROM)，并且可耦合到I/O子系统402以存储信息及指令。存储装置410是可用于存储指令及数据的非暂时性计算机可读介质的示例，当由处理器404执行时，所述指令及数据致使执行计算机实施的方法来执行所述技术中的一些或全部。

存储器406、ROM 408或存储装置410中的指令可包括一组或多组指令，所述指令被组织为模块、方法、对象、函数、例程或叫用。所述指令可被组织为一个或多个计算机程序、操作系统服务或包含移动app的应用程序。指令可包括：操作系统或系统软件；支持多媒体、编程或其他功能的一个或多个库；实施TCP/IP、HTTP或其他通信协议的数据协议指令或堆栈；解释并再现使用HTML、XML、JPEG、MPEG或PNG来编码的文件的文件处理指令；为图形用户接口(GUI)、命令行接口或文本用户接口再现或解释命令的用户接口指令；应用软件，例如办公套件、互联网接入应用、设计及制造应用、图形应用、音频应用、软件工程应用、教育应用、游戏或各种应用。所述指令可实施web服务器、web应用服务器或web客户端。指令可被组织为呈现层、应用层及数据存储层，例如使用结构化查询语言(SQL)或NoSQL的关系数据库系统、对象存储体、图形数据库、平面文件系统或其他数据存储装置。

计算装置400可经由I/O子系统402耦合到至少一个输出装置412。输出装置412可以是数字计算机显示器。可使用的显示器的示例包含触摸屏显示器或发光二极管(LED)显示器或液晶显示器(LCD)或电子纸显示器。计算装置400可包含其他类型的输出装置412，作为显示装置的替代或补充。其他输出装置412的示例包含打印机、票据打印机、绘图仪、投影仪、声卡或视频卡、扬声器、蜂鸣器或压电装置或其他听觉装置、灯或LED或LCD指示器、触觉装置、致动器或伺服系统。

输入装置414可耦合到I/O子系统402，用于将信号、数据、命令选择或手势传递给处理器404。输入装置414的示例包含触摸屏、麦克风、静态及视频数码相机、字母数字键及其他键、小键盘、键盘、图形输入板、图像扫描仪、操纵杆、时钟、开关、按钮、拨号盘、滑块或各种类型的传感器，例如力传感器、运动传感器、热传感器、加速度计、陀螺仪及惯性测量单元(IMU)传感器，或者各种类型的收发器，例如无线收发器，例如蜂窝式或Wi-Fi、射频(RF)或红外线(IR)收发器及全球定位系统(GPS)收发器。

另一类型的输入装置是控制装置416，其可执行光标控制或其他自动控制功能，例如在显示屏上的图形接口中导航，作为输入功能的替代或补充。控制装置416可以是触摸板、鼠标、轨迹球或光标方向键，用于将方向信息及命令选择传递给处理器404，并用于控制光标在显示器412上的移动。输入装置可在两个轴线(第一轴线(例如，x)及第二轴线(例如，y))上具有至少两个自由度，这允许装置规定平面中的位置。另一类型的输入装置是有线、无线或光学控制装置，例如操纵杆、棒、控制台、方向盘、踏板、换档机构或其他类型的控制装置。输入装置414可包含多个不同输入装置的组合，例如摄像机及深度传感器。

计算装置400可包含物联网(IoT)装置或其他计算器具，其中省略了输出装置412、输入装置414及控制装置416中的一者或多者。输入装置414可包括一个或多个照相机、运动检测器、温度计、麦克风、地震检测器、其他传感器或检测器、测量装置或编码器，并且输出装置412可包括特殊用途显示器，例如单线LED或LCD显示器、一个或多个指示器、显示面板、仪表、阀门、螺线管、致动器或伺服机构。

当计算装置400是移动或可携式计算装置时，输入装置414可包括耦合到GPS模块的全球定位系统(GPS)接收器，所述GPS模块能够对多个GPS卫星进行三角测量，确定并生成地理位置或位置数据，例如计算装置400的地球物理位置的经纬度值。输出装置412可包含硬件、软件、固件及接口，用于生成朝向主机424或服务器430引导的位置报告分组、通知、脉冲或心跳信号，或者规定计算装置400的位置的其他循环数据传输，单独地或与其他特殊用途数据组合。

计算装置400可使用所定制硬连线逻辑、至少一个ASIC或FPGA、固件或程序指令或逻辑来实施所述技术中的一些或全部，所述指令或逻辑在与计算装置400组合地被加载及使用或执行时致使或编程计算装置400作为特殊用途机器来操作。

由计算装置400执行的技术可响应于处理器404执行主存储器406中所含有的至少一个指令的至少一个序列来执行。此类指令可从另一存储介质(例如存储装置410)读入主存储器406。主存储器406中所含有的指令序列的执行致使处理器404执行所述技术中的一些或全部。可使用硬连线电路系统来代替软件指令或者与软件指令组合。

本文中所使用的术语“存储介质”是指存储致使机器以特定方式运行的数据或指令的任何非暂时性计算机可读介质。此种存储介质可包括非易失性介质或易失性介质。举例来说，非易失性介质包含光盘或磁盘，例如存储装置410。易失性介质包含动态存储器，例如存储器406。存储介质的通用形式包含例如硬盘、固态驱动器、快闪驱动器、磁性数据存储介质、任何光学或物理数据存储介质、存储器芯片等等。

存储介质相异于传输介质但可与传输介质结合使用。传输介质参与存储介质之间的信息传送。举例来说，传输介质包含同轴电缆、铜线及光纤，从而包含包括I/O子系统402的总线的线。传输介质也可采用声波或者光波的形式，例如在无线电波及红外线数据通信期间生成的那些。

各种形式的介质可涉及将至少一个指令的至少一个序列载送到处理器404以供执行。举例来说，指令最初可由远程计算机的磁盘或固态驱动器载送。远程计算机可将指令加载到其动态存储器中，并使用调制解调器通过例如光纤或同轴电缆或电话线的通信链路发送指令。计算装置400本地的调制解调器或路由器可接收通信链路上的数据，并转换数据以供计算装置400读取。举例来说，例如射频天线或红外线检测器的接收器可接收无线或光学信号中载送的数据，并且适当电路系统可将数据提供给I/O子系统402，例如将数据放置在总线上。I/O子系统402将数据载送到存储器406，处理器404从存储器406检索并执行指令。由存储器406接收的指令可以可选地在由处理器404执行之前或之后存储在存储装置410上。

计算装置400还包含耦合到总线402的通信接口418。通信接口418提供耦合到网络链路420的双向数据通信，网络链路420直接或间接连接到至少一个通信网络，例如网络422或互联网上的公共或私有云。举例来说，通信接口418可以是以太网网络接口、综合业务数字网络(ISDN)卡、电缆调制解调器、卫星调制解调器或调制解调器，以提供到对应类型的通信线路的数据通信连接，例如以太网电缆或任何种类的金属电缆或光纤线路或电话线。网络422广义地表示局域网(LAN)、广域网(WAN)、校园网、互联网或其任一组合。通信接口418可包括LAN卡，以提供到兼容LAN的数据通信连接，或者经接线以根据蜂窝无线电话无线网络标准发送或接收蜂窝数据的蜂窝无线电话接口，或者经接线以根据卫星无线网络标准发送或接收数字数据的卫星无线电接口。在任何此种实施方式中，通信接口618通过载送表示各种类型的信息的数字数据流的信号路径发送及接收电、电磁或光学信号。

网络链路420通常使用例如卫星、蜂窝、Wi-Fi或蓝牙技术直接或通过至少一个网络将电、电磁或光学数据通信提供给其他数据装置。举例来说，网络链路420可通过网络422提供到主机计算机424的连接。

此外，网络链路420可通过网络422提供连接，或者经由由互联网服务提供商(ISP)426操作的网络互连装置及/或计算机提供到其他计算装置的连接。ISP 426通过表示为互联网428的全球分组数据通信网络提供数据通信服务。服务器计算机430可耦合到互联网428。服务器430广义地表示具有或不具有管理程序的任何计算机、数据中心、虚拟机或虚拟计算实例，或者执行例如DOCKER或KUBERNETES的容器化程序系统的计算机。服务器430可表示使用不止一个计算机或实例来实施且通过传输web服务请求、在HTTP有效载荷中具有参数的统一资源定位符(URL)字符串、API叫用、app服务叫用或其他服务叫用来访问及使用的电子数字服务。

计算装置400及服务器430可形成分布式计算系统的元件，所述分布式计算系统包含其他计算机、处理集群、服务器群或者合作执行任务或执行应用或服务的其他计算机组织。服务器630可包括被组织为模块、方法、对象、函数、例程或叫用的一组或多组指令。所述指令可被组织为一个或多个计算机程序、操作系统服务或包含移动app的应用程序。指令可包括操作系统和/或系统软件；支持多媒体、编程或其他功能的一个或多个库；实施TCP/IP、HTTP或其他通信协议的数据协议指令或堆栈；解释或再现使用HTML、XML、JPEG、MPEG或PNG来编码的文件的文件格式处理指令；为图形用户接口(GUI)、命令行接口或文本用户接口再现或解释命令的用户接口指令；应用软件，诸如办公套件、互联网接入应用、设计及制造应用、图形应用、音频应用、软件工程应用、教育应用、游戏或各种应用。服务器430可包括web应用服务器，所述web应用服务器对呈现层、应用层及数据存储层进行托管，诸如使用结构化查询语言(SQL)或NoSQL的关系数据库系统、对象存储体、图形数据库、平面文件系统或其他数据存储装置。

计算装置400可通过网络、网络链路420及通信接口418发送消息并接收数据及指令，包含程序代码。在互联网示例中，服务器430可通过互联网428、ISP 426、本地网络422及通信接口418传输应用程序的请求代码。所接收代码可在其被接收时由处理器404执行，或者存储在存储装置410或其他非易失性存储装置中以供稍后执行。

基本软件系统

图5是可用于控制图4的计算装置400的操作的示例性基本软件系统500的框图。软件系统500及包含其连接、关系及功能的其组件仅意味着是示例，且并不意味着限制所述技术的实施方式。适合于实施所述技术的其他软件系统可具有不同组件，包含具有不同连接、关系及功能的组件。

提供软件系统500用于引导计算机系统400的操作。可存储在系统存储器(RAM)406中及存储在固定存储装置(例如，硬盘或快闪存储器)410上的软件系统500包含内核或操作系统(OS)510。

OS 510管理计算机操作的低级方面，包含管理表示为502-1、502-2、502-3、…、502-N的过程的执行、存储器分配、文件输入及输出(I/O)以及装置I/O。一个或多个应用程序可被“加载”(例如，从固定存储装置410传送到存储器406中)以由系统500作为一个或多个过程来执行。旨在供用于计算装置400上的应用或其他软件也可被存储为一组可下载计算机可执行指令，例如，用于从互联网位置(例如，Web服务器、app商店或其他在线服务)下载及安装。

应用程序指令的执行可以正被执行并由程序代码及其当前活动组成的计算机程序的实例的形式实施过程(例如，502-2)。取决于操作系统(OS)，过程(例如，502-3)可由并发地执行指令的多个执行线程组成。在此上下文中，计算机程序是指令的被动集合，而过程(例如，502-1)可以是那些指令的实际执行。数个过程(例如，502-1及502-2)可与同一程序相关联；例如，开始运行同一程序的数个实例通常意味着正在执行不止一个过程，或者最初作为单个过程启动的程序可能随后产生(例如，衍生)额外过程。

OS 510可实施多任务处理，以允许过程502-1、502-2、502-3、…、502-N共享处理器404。虽然每一处理器404或处理器的核心每次执行单个任务，但计算装置400可经编程以实施多任务处理，以允许每一处理器在正在执行的任务之间切换，而不必等待每一任务完成。当任务执行输入/输出操作时，当任务指示其可进行切换时，或者其在硬件中断时，可执行切换。通过快速执行上下文切换以提供多个过程同时并行执行的外观，可实施时间共享以允许交互式用户应用的快速响应。为了安全性及可靠性，OS 510可防止独立过程之间的直接通信，从而提供经严格调解及控制的过程间通信功能。

在一些实例中，过程502-1、502-2、502-3、…、502-N以及其实施的应用程序可在应用容器540内执行。应用容器通常是OS 510的操作模式，其中OS 510允许存在多个经隔离用户空间实例在OS 510上运行。应用容器540是一个此种实例的示例。替代地，实例本身有时也被称为区带、虚拟私有服务器、分区、虚拟环境、虚拟内核或监狱。应用容器提供一种机制，由此可在实例当中分配有限硬件计算资源，例如CPU时间及存储介质空间。

软件系统500包含图形用户接口(GUI)515，用于以图形方式(例如，“点击”或“触摸手势”)接收用户命令及数据。这些输入又可由系统500根据来自操作系统510或过程502-1、502-2、502-3、…、502-N的指令来执行动作。GUI 515还用于显示来自OS 510及过程502-1、502-2、502-3、…、502-N 502的操作结果，由此用户可提供额外输入或终止会话(例如，注销)。

OS 510可直接在计算装置400的裸硬件520(例如，处理器404)上执行。替代地，管理程序或虚拟机监视器(VMM)530可插置在裸硬件520与OS 510之间。在此配置中，VMM 530充当OS 510与计算装置400的裸硬件520之间的软件“缓冲”或虚拟化层。

VMM 530实例化并运行一个或多个虚拟机实例(“客户机”)。每一客户机包括诸如OS 510的“客户”操作系统，以及经设计以在客户操作系统上执行的一个或多个应用，例如应用502。VMM 530向客户操作系统提供虚拟操作平台，并管理客户操作系统的执行。

在一些实例中，VMM 530可允许客户操作系统运行，就好像其直接在计算装置400的裸硬件520上运行一样。在这些实例中，被配置为直接在裸硬件520上执行的同一版本的客户操作系统也可在VMM 530上执行，而无需进行修改或重新配置。换句话说，在一些实例中，VMM 530可将完全硬件及CPU虚拟化提供给客户操作系统。

在其他实例中，客户操作系统可经专门设计或配置以在VMM 530上执行。在这些实例中，客户操作系统“意识到”其在虚拟机监视器上执行。换句话说，在一些实例中，VMM 530可向客户操作系统提供半虚拟化。

云计算

所述技术可在“云计算”环境中实施。术语“云计算”在本文中一般用于描述一种计算模型，所述计算模型使得能够对诸如计算机网络、服务器、软件应用及服务等计算资源的共享池进行按需访问，并且允许以最少管理努力或服务提供商交互来快速供应及释放资源。

云计算环境(有时称为云环境或云)可通过各种不同方式来实施，以最大限度地满足不同要求。举例来说，在公共云环境中，底层计算基础设施由组织拥有，所述组织向其他组织或公众提供其云服务。相比来说，私有云环境一般仅供单个组织使用或在单个组织内部使用。社区云旨在由社区内的数个组织共享；而混合云包括两种或更多种类型的云(例如私有、社区或公共)，其通过数据及应用可移植性绑定在一起。

一般来说，云计算模型使得先前可能由组织自身信息技术部门提供的那些职责中的一些能够在云环境内作为服务层交付，以供消费者使用(根据云的公共/私有性质，在组织内或在组织外部)。取决于特定实施方式，由每一云服务层提供或在每一云服务层内的组件或特征的精确定义可能会有所不同，但通用示例包含：软件即服务(SaaS)，其中消费者使用在云基础设施上运行的软件应用，而SaaS提供商管理或控制底层云基础设施及应用。平台即服务(PaaS)，其中消费者可使用由PaaS提供商支持的软件编程语言及开发工具来开发、部署及以其他方式控制其自身应用，而PaaS提供商则管理或控制云环境的其他方面(例如，运行时间执行环境以下的所有内容)。基础设施即服务(IaaS)，其中消费者可部署及运行任意软件应用，及/或提供处理、存储、网络及其他基本计算资源，而IaaS提供商则管理或控制底层物理云基础设施(例如，操作系统层以下的所有内容)。数据库即服务(DBaaS)，其中消费者使用在云基础设施上运行的数据库服务器或数据库管理系统，而DbaaS提供商管理或控制底层云基础设施、应用及服务器，包含一个或多个数据库服务器。

本公开的其他方面

除非上下文另有明确指示，否则术语“或”在前述说明书及所附权利要求书中以其包含性意义(而非其排他性意义)使用，因此当用于例如连接一列表的元件时，术语“或”意指列表中的一个、一些或所有元件。

除非上下文另有明确指示，否则术语“包括”、“包含”、“具有”、“基于”、“囊括”等等以开放式方式在前述说明书及所附权利要求书中使用，并且不排除额外元件、特征、动作或操作。

除非上下文另有明确指示，否则诸如短语“X、Y及Z中的至少一者”的连接性语言应理解为传达物品、项等可以是X、Y或Z，或者其组合。因此，此种连接性语言并不旨在默认地要求X中的至少一者、Y中的至少一者及Z中的至少一者各自存在。

除非上下文另有明确指示，否则如在前述具体实施方式及所附权利要求书中所使用，单数形式“a/an(一个/一种)”及“该”也旨在包含复数形式。

除非上下文另有明确指示，否则在前述具体实施方式及所附权利要求书中，尽管术语第一、第二等在一些实例中在本文中用于描述各种元件，但这些元件不应受到这些术语的限制。这些术语仅用于将一个元件与另一元件区分开。举例来说，第一计算装置可被称为第二计算装置，并且类似地，第二计算装置可被称为第一计算装置。第一计算装置及第二计算装置都是计算装置，但其并非同一计算装置。

在前述说明书中，已参考众多具体细节描述这些技术，所述具体细节可根据实施方式的不同而变化。因此，说明书及图式被认为是说明性意义而不是限制性意义。

Claims (20)

1.一种计算机实施的方法，其包括：

从库的通用规范提取文档片段，所述通用规范包括源编程语言中的源代码；

识别所述文档片段的被中断文本内的第一结构化文本；

将所述第一结构化文本翻译为第二文本；以及

产生用于相应目标编程语言的文档输出，所述文档输出包括所述第二文本。

2.根据权利要求1所述的计算机实施的方法，其还包括：

将所述第一结构化文本翻译为多个文本，其中所述第二文本是所述多个文本中的一者；以及

产生用于多种相应目标编程语言的多个文档输出，其中每一文档输出包括所述多个文本中的相应文本，其中所述文档输出是所述多个文档输出中的一者。

3.根据权利要求1所述的计算机实施的方法，其中将所述第一结构化文本翻译为所述第二文本是基于：

确定所述第一结构化文本是指所述通用规范的所述源编程语言中所述源代码中所规定的值；

获得所述通用规范的所述源编程语言中所述源代码中的所述值；以及

基于所述值来形成所述第二文本。

4.根据权利要求3所述的计算机实施的方法，其中基于所述值来形成所述第二文本是基于：

将所述值翻译为不同但等效的值；以及

将所述不同但等效的值包含在所述第二个文本中。

5.根据权利要求1所述的计算机实施的方法，其中所述将所述第一结构化文本翻译为所述第二文本是基于：

确定所述第一结构化文本是指所述通用规范的第一命名类型的构建块，所述第一类型的构建块由所述源编程语言提供以用于精心制作所述源编程语言中的接口；并且

其中所述第二文本包括对所述相应目标编程语言中源代码的第二命名类型的构建块的引用，所述相应目标编程语言中所述源代码的所述第二命名类型的构建块基于所述通用规范的所述第一命名类型的构建块来生成，所述相应目标编程语言中的所述第二类型的构建块由所述相应目标编程语言提供以用于精心制作所述相应目标编程语言中的接口。

6.根据权利要求5所述的计算机实施的方法，其中所述引用是超链接。

7.根据权利要求5所述的计算机实施的方法，其中由所述源编程语言提供以用于精心制作所述源编程语言中的接口的所述第一类型的构建块是类别。

8.根据权利要求5所述的计算机实施的方法，其中所述相应目标编程语言中由所述相应目标编程语言提供以用于精心制作所述相应目标编程语言中的接口的所述第二类型的构建块是类别的成员函数。

9.根据权利要求1所述的计算机实施的方法，其还包括：

自动调用所述用于所述相应目标编程语言的文档生成器以从所述文档输出生成文档，其中所生成文档符合社区中程序员对所述相应目标编程语言的期望。

10.根据权利要求1所述的计算机实施的方法，其中：

所述被中断文本是第一被中断文本；

所述第一结构化文本在所述第一被中断文本中具有第一位置；

所述第二文本是结构化文本；

所述文档输出包括第二被中断文本；并且

所述文档输出经产生，使得所述第二文本在所述第二被中断文本中具有第二位置，所述第二位置在语义上等效于所述第一结构化文本在所述第一被中断文本中的所述第一位置。

11.根据权利要求1所述的计算机实施的方法，其中：

所述第一结构化文本包括文档片段语言中的第一用法示例；并且

所述第二文本包括所述相应目标编程语言中的第二用法示例，所述第二用法示例在功能上等效于所述第一用法示例。

12.根据权利要求11所述的计算机实施的方法，其还包括：

识别所述第一用法示例中的通用概念；

将通用概念语料库用于所述相应目标编程语言以将所述第一用法示例中的所述通用概念翻译为所述相应目标编程语言中的功能上等效的通用概念；以及

将所述功能上等效的通用概念包含在所述第二用法示例中的所述相应目标编程语言中。

13.根据权利要求1所述的计算机实施的方法，其中所述通用规范是第一通用规范；并且其中所述将所述第一结构化文本翻译为所述第二文本是基于：

确定所述第一结构化文本是指第二通用规范的第一命名类型的构建块，所述第一类型的构建块由所述源编程语言提供以用于精心制作所述源编程语言中的接口；并且

其中所述第二文本包括对以所述相应目标编程语言中源代码的第二命名类型的构建块的引用，所述源代码从所述第二通用规范派生，所述相应目标编程语言中所述源代码的的所述第二命名类型的构建块基于所述第二通用规范的所述第一命名类型的构建块来生成，所述相应目标编程语言中的所述第二类型的构建块由所述相应目标编程语言提供以用于精心制作所述相应目标编程语言中的接口。

14.根据权利要求1所述的计算机实施的方法，其中：

所述被中断文本是第一被中断文本；

所述第一被中断文本包括第一人类语言中的第一散文；

所述第一结构化文本在所述第一被中断文本中具有相对于所述第一散文的第一位置；

所述第二文本是结构化文本；

所述文档输出包括第二被中断文本；

所述方法还包括将所述第一散文翻译为第二人类语言中的第二散文；并且

所述文档输出经产生，使得所述第二文本在所述第二被中断文本中具有相对于所述第二散文的第二位置，所述第二位置在语义上等效于所述第一结构化文本在所述第一被中断文本中相对于所述第一散文的所述第一位置。

15.一种或多种存储指令的非暂时性存储介质，当由一个或多个计算装置执行时，所述指令致使所述一个或多个计算装置执行以下操作：

从库的通用规范提取文档片段，所述通用规范包括源编程语言中的源代码；

识别所述文档片段的被中断文本内的结构化文本；

将所述结构化文本翻译为用于多种目标编程语言的多个文本；以及

为所述多种目标编程语言产生多个文档输出。

16.根据权利要求15所述的一种或多种非暂时性存储介质，其还包括指令，当由所述一个或多个计算装置执行时，所述指令致使所述一个或多个计算装置执行以下操作：

对于所述多种目标编程语言中的至少两种目标编程语言中的每一种，自动调用用于所述目标编程语言的文档生成器以从为所述目标编程语言产生的所述文档输出生成文档，其中所生成文档符合语言目标编程语言社区中程序员的期望。

17.根据权利要求15所述的一种或多种非暂时性存储介质，其还包括指令，当由所述一个或多个计算装置执行时，所述指令致使所述一个或多个计算装置执行以下操作：

识别所述第一结构化文本中以文档片段语言表达的用法示例；

识别所述第一结构化文本中所述用法示例的预期输出；

对于所述多种目标编程语言中的每一种，基于所述通用规范的所述源编程语言中的源代码来派生所述目标编程语言中的所述源代码；

对于所述多种目标编程语言中的每一种，基于所述目标编程语言中的所述源代码来生成用于所述目标编程语言的库；

对于所述多种目标编程语言中的至少两种目标编程语言中的每一种，基于以所述文档片段语言表达的所述用法示例来派生以所述目标编程语言表达的用法示例；

对于所述多种目标编程语言中的所述至少两种目标编程语言中的每一种，基于以所述目标编程语言表达的所述用法示例以及用于所述目标编程语言的所述库来生成用于所述目标编程语言的测试程序；以及

对于所述多种目标编程语言中的所述至少两种目标编程语言中的每一种，执行用于所述目标编程语言的所述测试程序，将所述测试程序执行的输出与所述预期输出进行比较，并将所述比较的结果输出到用户接口、文件或数据库。

18.根据权利要求15所述的一种或多种非暂时性存储介质，其中所述多种目标编程语言包括以下编程语言中的至少一种：C、JAVA、PYTHON、C++、C#、JAVASCRIPT、PHP、SWIFT、R、LISP、FORTRAN、ADA、PASCAL、GROOVY、RUBY、GO、OBJECTIVE-C、DART、SCALA或LUA。

19.一种系统，其包括：

一个或多个计算装置，其被配置为执行以下操作：

从库的通用规范提取文档片段，所述通用规范包括源编程语言中的源代码；

识别所述文档片段的第一被中断文本内的第一结构化文本；

将所述第一结构化文本翻译为第二结构化文本；以及

产生用于相应目标编程语言的文档输出，所述文档输出包括第二被中断文本内的所述第二结构化文本。

20.根据权利要求19所述的系统，其中所述一个或多个计算装置还被配置为执行以下操作：

将所述第一结构化文本翻译为至少八个结构化文本，其中所述第二结构化文本是所述至少八个结构化文本中的一者；以及

产生用于至少八种目标编程语言的至少八个文档输出，其中每一文档输出包括所述至少八个结构化文本中的相应文本，其中所述文档输出是所述至少八个文档输出中的一者。