Sandcastle Help File Builder[Missing <summary> documentation for ""]
来源:互联网 发布:淘宝网开放平台 编辑:程序博客网 时间:2024/05/22 08:04
实现SHFB的软件环境:
首先:需要安装Sandcastle,搜索下载最新版本。
其实:就是chm文件的制作软件HTML Help Workshop。路径:http://download.csdn.net/detail/ybb350680013/9918704
实现步骤:
第一:把生成帮助的工程的属性做下修改,右键工程,属性,生成,下面的输出框中有一个生成XML文件选项,打勾。文件会把工程中所有类,方法,属性上的注释保存下来。
第二:启动shfb,然后新建一个工程,名称可以随意指定。这里主要说说几个比较重要的属性设置问题:
1:Documentation Sources,是需要生成详细注释的工程。如果最外层工程有对其它工程的引用,而且我们希望看到所有引用的类,就需要把所有被引用的工程都添加进来。否则用户点击外层类时,被引用的类上面不会有链接,即我们看不到被引用类的内容。
2:References:设置一些工程的依赖项。
3:FrameworkVersion: 选择对应的Framework版本 ,最新版的shfb的默认设置是.net 3.5。
4:HelpFileFormat : 选择需要生成的文档的格式. 这里选定的格式要在下面对应的地方进行设置。对于不同的格式还需要安装不同的编译工具 Helpe1x(chm)需要安装Microsoft HTML Help,Helper2x(Hxs)需要安装 Hxcomp.
5:NamespaceSummaries: 选择需要生成的命名空间,直接点击开窗选择。
6:Lanugages :语言,如果文档中有中文,最好选择中文。
7:CopyrightHref:版权链接,例如http://www.xxx.com/
8:CopyrightText: 版权文字 ,xx公司所有
9:HelpTitle: 文档标题
10:HtmlHelpName:文档生成文件名称
11:PresentationStyle: 支持vs 2005,Prototype等格式 ,根据自己需要选择
12: OutputPath:生成路径,即最后chm文件存放位置,当然除了CHM还有些其它文件。
13:HtmlHelp1xCompilerPath:可以自定义html help的安装路径。
14:SandcastlePath:可以自定义sandcastel的安装路径。
15:Missing Tags: 设置需要显示的备注信息。
到此,我们就可以点击软件窗口上的buile the help file按钮,就可以按预期进行生成文档了。如果没有特殊情况,运行期间不会发生任何错误,我们会成功的在输出目录中发现chm文件,但有些情况还是需要注意一下的:
第一:在添加Documentation Sources时,不能在路径中包含.h的字样,例如.Hotel.Host\bin这种路径是不合法的,最后hhc软件会报错。
第二:References项中不能存在重复项。
如何正常编写注释,来生成详细可用的帮助文档?
1:类的注释。一般分为summary以及remarks两部分。
/// <summary> /// 体验账号检测 /// </summary> /// <param name="phone">手机号码</param> /// <returns></returns> public HttpResponseMessage Get(string phone) { return ToJson(experienceUser.Expired(phone)); }
2:方法的注释。除了类上面的summary,remarks,还可以加上example,在其中的code标签中加上实例代码等等。
/// 平台邀请用户进行手机点评方法
/// </summary>
/// <param name="request">用户点评信息</param>
/// <returns>点评处理结果</returns>
/// <remarks>
/// 会把点评发送结果发送到用户手机中
/// </remarks>
/// <example>
/// <code>
/// HotelCommentWcfClient target = new HotelCommentWcfClient();
/// Elong.Hotel.ServiceAgent.Test.HotelCommentWcf.HotelCommentRequestInfo request = null;
/// request = new Elong.Hotel.ServiceAgent.Test.HotelCommentWcf.HotelCommentRequestInfo();
/// request.HotelOrderLast4 = "3716";
/// request.Mobile = "********";
/// request.RecommentContent = "aaa";
/// Elong.Hotel.ServiceAgent.Test.HotelCommentWcf.ResponseBaseInfo actual;
/// actual = target.SMGAndComment(request);
/// </code>
/// </example>
public ResponseBaseInfo SMGAndComment(HotelCommentRequestInfo request)
3:属性的注释。这个是最简单的,一般有summary块就行了,其中有一个value块,可以针对默认值进行描述。
总结:Sandcastle Help File Builder能够非常好的和VS合作,制作出MSDN风格的帮忙文档,即有效的对项目保存了技术文档又降低了沟通成本。
PS:此类错误及解决办法,[Missing <summary> documentation for ""]
此时发现,在项目中,添加了对应的备注,依然没有写入到帮助文档。如图:
原因是因为VS只是编译的DLL中,是不包含注释的。
解决办法:在VS中输出一个XML备注文档。如图:
- Sandcastle Help File Builder[Missing <summary> documentation for ""]
- sandcastle , HTML Help Workshop, Sandcastle Help FIle Builder 出错经验总结
- .Net 2.0 的文档生成器 Sandcastle Help File Builder
- .net下帮助文件生成程序对比(NDoc、Sandcastle、Sandcastle Help File Builder)
- SHFB-Sandcastle Help File Build vs文档生成工具安装及配置
- autorun file for ohasd is missing
- C# 显示注释 Documentation summary
- missing file
- FOR HELP
- Flex Documentation Zip File
- XNB file format documentation
- autorun file for ohasd is missing(2)
- dpkg: warning: files list file for package `*’ missing 解决方法
- SVN问题: File is scheduled for addition, but is missing
- The project description file (.project) for 'Servers' is missing
- 解决The project description file (.project) for 'xxx' is missing
- Java documentation in Windows Help format
- autocAD ObjectARX Documentation H3Viewer help viewer
- 利用percona-toolkit中pt-online-schema-change功能对表进行online ddl
- activeMQ深入了解—队列模式手动控制消费
- 操作系统真相还原——MBR
- ajax嵌套
- codeforces B. The number on the board
- Sandcastle Help File Builder[Missing <summary> documentation for ""]
- eclipse远程调试Tomcat方法
- MySQL Binlog的介绍以及主从配置注意
- 对Kth number的一点小研究——主席树
- idea 控制台中文乱码
- VMware Workstation 错误(虚拟机似乎正在使用无法获得使用权)
- android开源项目
- 课时14 Linux用户基础
- oracle基本操作语句