[译]记录头文件
By robot-v1.0
本文链接 https://www.kyfws.com/applications/documenting-header-files-zh/
版权声明 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!
- 8 分钟阅读 - 3825 个词 阅读量 0[译]记录头文件
原文地址:https://www.codeproject.com/Articles/5004/Documenting-Header-Files
原文作者:G. Steudtel
译文由本站 robot-v1.0 翻译
前言
This tool will turn a header file into an XML and/or HTML file for documentation purposes. The output may be merged with previously created or edited XML files.
该工具会将头文件转换为XML和/或HTML文件,以用于记录.输出可以与先前创建或编辑的XML文件合并.
剩下243个文件和17天(243 Files and 17 Days left)
从前,有个老板告诉他的员工,客户想要一个完整记录的源代码.尽管源代码中充斥着注释,但其中一些注释甚至有用,但这并不是客户认为要记录的内容.该客户想到了类似MFC中的文档之类的东西.因此,老板告诉他的员工记录该项目的每个头文件.每个变量,每个函数和每个类.他告诉他们要在截止日期完成.(Once upon a time, there was a boss, who told his employees, that the customer wanted a fully documented source code. Though the source code was strewn with comments, some of them even useful, this was not what the customer thought of being documented. This customer thought of something like the documentation in the MFC or that alike. So, the boss told his employees to document each header file of the project. Each variable, each function, and each class. And he told them to have it finished at deadline day.)
这个故事是,为什么它以每个童话故事而不是噩梦结尾.(And this story is, why it ended as every fairy tale, and not as nightmare.)
配置(Setting up)
我们决定分开努力.一个人应该寻找对我们有帮助的应用程序,一个人应该概述文档的布局,一个人应该找出如何从头文件中检索信息.六个小时后,我们见了面,得出的结论是我们很可能会失败.主要问题是生成的文档文件的格式,每个头文件消耗大约3到4个小时,整个过程大约需要800个小时或100个工作日.那是我创建新管理规则的时间:(We decided to split our efforts. One should seek for applications that could help us, one should sketch the layout of the documentation, and one should find out how to retrieve the information from a header file. After six hours, we met, and came to the conclusion that most likely we would fail. The main problem being the formatting of the resulting documentation files, which consumes about 3 to 4 hours per header file, resulting in roughly 800 hours or 100 working days for the whole process. That’s when I created a new management rule:)
- 如果您想做一些愚蠢的事情,请找一个愚蠢的人.(If you want something stupid to be done, find someone stupid.)
- 如果您希望快速完成任务,请找一个更愚蠢的人.(If you want it to be done fast, find someone more stupid.)
- 如果您希望重复进行此操作,请找到一个白痴.(If you want it be done repeatedly, find an idiot.) 因此,我环顾四周,找不到合适的人.我照了镜子,可能很近,但仍然不太合适.我看着桌子下面,那里是:我的电脑.两天后,有一个程序正在运行,该程序读取头文件并将其转换为带格式的HTML文件,其中包含制作文档所需的所有信息.接下来的十天只是(So, I looked around and I could not find an appropriate person. I looked into the mirror, probably close to, but still not quite fitting. I looked under my desk, and there it was: my computer. Two days later then, there was a program running, that read a header file and turned it into a formatted HTML file with all the information needed to make a documentation. The next ten days were just a)**F(F)**印(ind)**一种(A)nd(nd)[R(R)**用更明智的方式代替那些无处不在的"这里应该是描述".将这些文件绑定到HTML帮助项目只是一个令人愉快的甜点.(eplace of those ubiquitous “Here should be a description” by something more sensible. Binding those files to an HTML help project was just a delightful dessert.)
没有文件,还剩2天(No Files and 2 Days left)
老板和顾客感到非常高兴,三个程序员从此过着幸福的生活,仍然在等老板给他们付啤酒.(The boss and the customer were highly pleased, and the three programmers lived happily ever after, still waiting for the boss to pay them a beer.)
后果(Aftermath)
好吧,老板不仅可以付给我们一杯啤酒,而且当我失业时,我决定将这个应用程序变成一个更有用的文档系统.文档布局被转换为(Well, the boss could not only pay us a beer, and when I went jobless, I decided to turn this application into a more useful documentation system. The documentation layout was cast into a)**d(d)**招揽(ocument)****铭牌(emplate)**d(d)**定义,并且输出将与现有XML文件合并.这就是结果.(efinition, and the output could be merged with an existing XML file. And this is the result.)
该程序(The Program)
该程序用于记录C ++源文件的头文件.如果将其与其他文本一起提供,例如电子邮件或真实文献,您会发现它什么也没记录. ;)感谢本布莱恩特(*This program is for documenting header files of C++ sources. If you feed it with other texts, like e-mails or real literature, you will find out that it will document nothing. ;) Thanks to Ben Bryant's*)
CMarkup` 类,则无需在系统上运行任何XML引擎.因此,运行该程序,找到一个头文件,告诉程序将文档文件放置在什么位置,并感到失望.该程序仅格式化.该文档必须由您编写.还记得管理规则吗? :)然后运行任何文本编辑器,加载创建的XML文件,并用要共享的信息替换那些"这里应该是…".再次运行该程序,加载相同的头文件,并告诉程序读取修改后的XML文件.保存并观看结果.(class, you do not need any XML engine running on your system. So, run the program, find a header file, tell the program where to place the documentation files, and be disappointed. This program only does formatting. The documentation has to be written by you. Remember the management rule? :) Then run any text editor, load the XML file created, and replace those “Here should be a…” with the information you want to share. Run this program again, load the same header file, and tell the program to read the modified XML file. Save and watch the result.)
鼠标点击后(Behind the Mouse Clicks)
在启动时,程序尝试读取一个INI文件,该文件告诉它要忽略的内容(宏)以及不返回值的单词(例如(On start up, the program tries to read an INI file, which tells it what to ignore (macros) and what words are not return values (like) virtual
).().)
找到头文件时,将解析此文件.详细地说,这意味着将删除所有注释,并将跨越多行的字符串或源代码行合并为一行. INI文件中定义的所有宏都将被删除.所有以预处理器符号开头的行((When you locate a header file, this file is parsed. In detail, this means, all comments are stripped, and strings or source lines spanning more than one line are merged to one single line. All macros defined in the INI files are removed. All lines starting with the preprocessor sign () #
)被删除,只有来自() are eliminated, only the information from the) #include
行被存储.所有连续的空格都减少为一个空格字符.之后,将生成的文本"美化",也就是将其转换成易于解析的形式.然后扫描结果,并将有关变量,函数和类的信息存储到某些结构中.头文件的路径和名称用于为输出文件(HTML和XML)创建合理的名称.(lines are stored. All continuous white spaces are reduced to one space character. After that, the resulting text is ‘beautified’, that is, brought into a form for easier parsing. Then the result is scanned, and the information for variables, functions, and classes is stored away into some structures. The path and name of the header file is used to create reasonable names for the output files (HTML and XML).)
当您告诉程序读取XML文件时,该文件的信息将根据存储的信息进行调整.这样,XML文件的任何合适的描述部分都会进入变量,函数或类的适当描述部分.仅描述部分用于合并,所有其他内容仅用于解决头文件的正确片段.唯一的例外是CPP包含列表,该列表也取自XML文件.如果尚未存储任何信息,则仅检索这些信息.这样,您可以使用多个XML文件来检索信息.然后,您可以选择如何创建结果HTML文件.如果您不打算使用HTML帮助研讨会等,请不要检查(When you tell the program to read an XML file, the information of this file is adjusted with the information stored. That way, any fitting description part of the XML file finds its way into the appropriate description part of the variable or function or class. Only the description part is used for merging, all the other stuff is only needed to address the correct fragment of the header file. The only exception is the CPP include list, which is taken from the XML file too. Those information are only retrieved, if no information was already stored. That way, you can use more than one XML file to retrieve the information. Then you may choose how the resulting HTML file shall be created. If you do not plan to use the HTML Help workshop or alike, please do not check the)*创建拆分文件(Create Splitfile)*框,也不创建自动关键字框.无论单选按钮如何,生成的XML文件将始终存储所有信息.这些按钮和复选框仅用于HTML输出.该程序更类似于XSL(T)文件.它读取格式错误的文件(头文件),将其转换为格式正确的XML文件,然后将该XML文件转换为HTML文件.(box neither the Create automated Keyword box. The resulting XML file will always store all informations, regardless of the radio buttons. Those buttons and checkboxes are only used for HTML output. This program resembles more to a XSL(T) file. It reads an ill formed file (header file), transforms it into a well formed XML file, and then turns this XML file into an HTML file.)
源代码(The Source Code)
该程序原本计划是一个基于对话框的应用程序,但是出于一个原因和一个原因,我使用了单个文档类型:(This program was planned to be a dialog based application, but I used the single document type for one and only one reason:)
- 打印预览.(Print Preview.) 意识到会产生大量文本,我寻找了一些不保存文件,而是及时读取结果的方法.因为在读取输出时可以很容易地察觉到大多数错误,所以我使用了打印预览功能在屏幕上显示该过程的各个阶段.我离开了此功能,因此如果您和我有相似的需求,则可以查看源代码.文字部分几乎全部包含在一个文件中((Recognizing that a lot of text would be produced, I looked for some means not to save files, but to read the results just in time. Because most errors occurring can be perceived easily when reading the output, I used the print preview feature to display various stages of the process on screen. I left this feature so you can have a look at the source code if you are in a similar need as I was. The textual part is almost exclusively enclosed in one file ()TextStrings.cpp(TextStrings.cpp)),以便于本地化.生产部分(() for ease of localization. The productive part ()CreateOutputxxx.cpp(CreateOutputxxx.cpp)和(, and)TextStringsxxx.cpp(TextStringsxxx.cpp))也针对每种类型分开,因此更容易将其用于不同的文档类型(例如RTF). INI文件和头文件的解析可能很有趣,但这只是普通的编程技术.() is also separated for each type, so it is easier to adopt it for different document types (E.g., RTF). The parsing of the INI file and of the header file might be interesting read, but is just plain programming technique.)
注意事项(Caveats)
提供的源代码将(The provided source code will)**不(not)**编译.文件(compile. The files)*CMarkup.cpp/h(CMarkup.cpp/h)*缺失.科比先生不希望他的课程可以在其他地方上载.我理解并完全接受他的推理.因此,如果您想/需要修改此源代码,请查看(are missing. Mr. Bryant does not want (t)his class to be uploadable from different places. I understand and accept fully his reasoning. So if you want/need to modify this source code, please have a look at) 第一对象(FirstObject) 第一.可以理解,在下载文件之前,您必须阅读并同意许可规定.您需要CMarkup V6.5评估版.(first. It is understood, that before downloading the files, you must read and agree to the licensing regulations. You need CMarkup V6.5 Evaluation release.)
许可
本文以及所有相关的源代码和文件均已获得The Code Project Open License (CPOL)的许可。
C++ VC6 WinXP Win2003 Windows Win2K MFC Visual-Studio Dev 新闻 翻译