关闭。这个问题是opinion-based .它目前不接受答案。
想改善这个问题吗？更新问题，以便可以通过 editing this post 用事实和引文回答问题.
3年前关闭。
Improve this question
我正在编写一个 C++ 静态库，并且我一直在对实现文件中的 doxygen 注释进行注释。我从来没有真正关心过文档，但我现在正在做一些需要为用户很好地记录的事情，而且我正在努力改变我以前只想编码而不是用更好的软件工程记录的坏习惯做法。
无论如何，前几天我意识到我需要几种不同类型的文档，一种是供库用户使用的(doxygen 手册)，然后是为我自己或 future 的维护者提供更多处理实现细节的评论。
我的解决方案之一是将文件、类和方法的 doxygen 注释放在实现文件的底部。在那里，它们将被排除在外，我可以在方法定义中/周围包含正常的注释，以使程序员受益。我知道这需要更多的工作，但这似乎是我实现两种不同类型的评论/文档的最佳方式。您是否同意或有任何可能有用的解决方案/原则。我环顾了网站，但找不到任何处理此问题的线程。
此外，我真的不想在界面文件中乱扔注释，因为我觉得让界面不言自明会更好。如果用户需要更深入地了解库界面，我宁愿将手册作为用户可以查看的地方。我在正确的轨道上吗？
任何想法或评论都非常感谢。
编辑:
感谢大家的意见。我从听他们的故事中学到了很多。我想我对如何将我的用户手册与对维护者有用的代码注释分开有更好的理解。我喜欢@jalf 有一个“散文”风格的手册来帮助解释如何使用库的想法。我真的认为这比引用手册更好。话虽如此……我也觉得引用手册可能真的派上用场。我想我会将他的建议与其他人的想法结合起来，并尝试创建一个混合体。(散文手册(使用页面、部分、小节等 doxygen 标签)链接到引用手册。)我喜欢 @jalf 的另一个建议代码的想法是没有完整的手动插入其中。我可以通过将我所有的 doxygen 注释放在实现文件的底部来避免这种情况。这使得标题干净，实现干净，以放置对维护实现的人有用的注释。我们将看看这在现实中是否可行。这些只是我对到目前为止所学知识的想法。我并不肯定我的方法会奏效甚至实用。只有时间会给出答案。
最佳答案
我认为最好的方法是使用 Doxygen 作为头文件来描述(向用户)如何使用每个类/方法，并使用 .cpp 文件中的注释来描述实现细节。
关于c++ - 双重目的代码注释(用户和维护者)...如何？，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/2090619/
我正在学习如何使用Nokogiri，根据这段代码我遇到了一些问题:require'rubygems'require'mechanize'post_agent=WWW::Mechanize.newpost_page=post_agent.get('http://www.vbulletin.org/forum/showthread.php?t=230708')puts"\nabsolutepathwithtbodygivesnil"putspost_page.parser.xpath('/html/body/div/div/div/div/div/table/tbody/tr/td/div
总的来说，我对ruby还比较陌生，我正在为我正在创建的对象编写一些rspec测试用例。许多测试用例都非常基础，我只是想确保正确填充和返回值。我想知道是否有办法使用循环结构来执行此操作。不必为我要测试的每个方法都设置一个assertEquals。例如:describeitem,"TestingtheItem"doit"willhaveanullvaluetostart"doitem=Item.new#HereIcoulddotheitem.name.shouldbe_nil#thenIcoulddoitem.category.shouldbe_nilendend但我想要一些方法来使用
关闭。这个问题是opinion-based.它目前不接受答案。想要改进这个问题？更新问题，以便editingthispost可以用事实和引用来回答它.关闭4年前。Improvethisquestion我想在固定时间创建一系列低音和高音调的哔哔声。例如:在150毫秒时发出高音调的蜂鸣声在151毫秒时发出低音调的蜂鸣声200毫秒时发出低音调的蜂鸣声250毫秒的高音调蜂鸣声有没有办法在Ruby或Python中做到这一点？我真的不在乎输出编码是什么(.wav、.mp3、.ogg等等)，但我确实想创建一个输出文件。
给定这段代码defcreate@upgrades=User.update_all(["role=?","upgraded"],:id=>params[:upgrade])redirect_toadmin_upgrades_path,:notice=>"Successfullyupgradeduser."end我如何在该操作中实际验证它们是否已保存或未重定向到适当的页面和消息？ 最佳答案 在Rails3中，update_all不返回任何有意义的信息，除了已更新的记录数(这可能取决于您的DBMS是否返回该信息)。http://ar.ru
我在我的项目目录中完成了compasscreate.和compassinitrails。几个问题:我已将我的.sass文件放在public/stylesheets中。这是放置它们的正确位置吗？当我运行compasswatch时，它不会自动编译这些.sass文件。我必须手动指定文件:compasswatchpublic/stylesheets/myfile.sass等。如何让它自动运行？文件ie.css、print.css和screen.css已放在stylesheets/compiled。如何在编译后不让它们重新出现的情况下删除它们？我自己编译的.sass文件编译成compiled/t
我想将html转换为纯文本。不过，我不想只删除标签，我想智能地保留尽可能多的格式。为插入换行符标签，检测段落并格式化它们等。输入非常简单，通常是格式良好的html(不是整个文档，只是一堆内容，通常没有anchor或图像)。我可以将几个正则表达式放在一起，让我达到80%，但我认为可能有一些现有的解决方案更智能。 最佳答案 首先，不要尝试为此使用正则表达式。很有可能你会想出一个脆弱/脆弱的解决方案，它会随着HTML的变化而崩溃，或者很难管理和维护。您可以使用Nokogiri快速解析HTML并提取文本:require'nokogiri'h
我正在寻找执行以下操作的正确语法(在Perl、Shell或Ruby中):#variabletoaccessthedatalinesappendedasafileEND_OF_SCRIPT_MARKERrawdatastartshereanditcontinues. 最佳答案 Perl用__DATA__做这个:#!/usr/bin/perlusestrict;usewarnings;while(){print;}__DATA__Texttoprintgoeshere 关于ruby-如何将脚
如何在buildr项目中使用Ruby？我在很多不同的项目中使用过Ruby、JRuby、Java和Clojure。我目前正在使用我的标准Ruby开发一个模拟应用程序，我想尝试使用Clojure后端(我确实喜欢功能代码)以及JRubygui和测试套件。我还可以看到在未来的不同项目中使用Scala作为后端。我想我要为我的项目尝试一下buildr(http://buildr.apache.org/)，但我注意到buildr似乎没有设置为在项目中使用JRuby代码本身!这看起来有点傻，因为该工具旨在统一通用的JVM语言并且是在ruby中构建的。除了将输出的jar包含在一个独特的、仅限ruby
Rackup通过Rack的默认处理程序成功运行任何Rack应用程序。例如:classRackAppdefcall(environment)['200',{'Content-Type'=>'text/html'},["Helloworld"]]endendrunRackApp.new但是当最后一行更改为使用Rack的内置CGI处理程序时，rackup给出“NoMethodErrorat/undefinedmethod`call'fornil:NilClass”:Rack::Handler::CGI.runRackApp.newRack的其他内置处理程序也提出了同样的反对意见。例如Rack
在rails源中:https://github.com/rails/rails/blob/master/activesupport/lib/active_support/lazy_load_hooks.rb可以看到以下内容@load_hooks=Hash.new{|h,k|h[k]=[]}在IRB中，它只是初始化一个空哈希。和做有什么区别@load_hooks=Hash.new 最佳答案 查看rubydocumentationforHashnew→new_hashclicktotogglesourcenew(obj)→new_has
