标签: documentation

我试图从 Swagger 文档向本地 API 发出请求，但当我发出请求时它总是给出此错误

阅读在线文档有用和有趣的内容是什么？

Disclamer: 虽然这个问题有自私的起源(我在写文档,并且,自然希望它是在那里最好的一个),我相信其他人可以采取的答案爱维稳特.另外,虽然文档不是编程,但我仍然认为在这里问这个问题是合适的,因为如果编程的话你需要记录内容.

详细说明: 这个问题是针对在线文档的,因为我认为在1500页的页面和网页/网站的动态之间有很大的不同.

假设有一个叫做WhizBangDaemon的新的令人兴奋的服务器,你几乎一无所知,你决定在业余时间尝试学习它.应该有哪些部分,因为文档有用且有趣并且让您阅读它？

请随时提供良好现有示例的链接,并解释您喜欢它们的原因.

这个问题的另一种解决方法是:什么样的showstoppers让你对阅读一套文档失去兴趣？

回答:

在答案之间重新定位一些重复出现的主题:

• 快速浏览
• 介绍性文本/教程/示例
• 不仅仅是API文档
• 分为许多小部分(可能与第一点有关)
• 简明扼要
• 搜索设施
• #anchors用于链接
• 可下载的格式

我刚刚开始了一项新工作,并且正在尝试熟悉330多个项目的大型C#解决方案.理想情况下,我想将注释和问题附加到代码片段而不实际编辑代码本身.

是否有一个工具可用于注释C#源代码而无需实际编辑代码本身.理想情况下,我想要一个"泡沫"类型的评论机制,类似于MS Word在文档中显示评论的方式.

是否有可下载的Rails指南的离线版本？

我正在使用Qt Creator,我决定要记录我编写的函数,所以我把光标放在我的函数定义上面并输入/**<ENTER>如下:

/**<ENTER>
void MyClass::myFunction(int myArg)
{
...

Qt Creator自动扩展了评论:

/**
 * @brief MyClass::myFunction
 * @param myArg
 */
void MyClass::myFunction(int myArg)
{
...

这是什么？它在哪里记录？

我可以使用它来生成我自己的Qt Assistant qch帮助文件吗？

我注意到内置的Matlab函数可以有多行可能的输入配置,如下所示

而不是公正的

我必须承担他们使用一个类似于inputParser配合使用的varargin,但我已经在试图复制这一功能是不成功的.我希望能够做到这一点,但我开始觉得这只是你可以用内置函数做的事情.

我想到或尝试过的事情是:

1. 解析帮助文档(不成功)
2. 单独文件中的信息
3. 为多个类创建相同的函数(不成功)
4. 创建一个功能齐全的inputParser(不成功)

有没有人能够做到这一点？

我正在尝试改进我的javascript代码的文档,并遵循JSDoc指南http://usejsdoc.org/.

我找不到如何记录故意的副作用.例如,以下方法:

/**
  * @description
  *   Paints the object red.
  * @return
*/
Painter.paintItRed = function(someObj){
    someObj.color = "red";
};

您如何记录该方法直接作用于传递的对象的事实？一个不同的例子:

/**
  * @description
  *   If the user has not setUp a config, show config Modal.
  * @return
*/
User.checkConfig = function(user){
    if(!user.config.valid){
       showConfigModal();
    }
};

这些是人为的例子和可能的"代码味道",但这是另一个问题.我正在研究如何记录这种行为(好的或坏的)的一些最佳实践.也许比这更好的东西//IMPORTANT!! This method is dangerous!

将Xcode更新为6.2后,大多数UI类引用都缺少文档查看器中的内容表.还有其他人遇到过这个问题吗？有没有办法在文档查看器中显示内容表,就像以前一样？

在我的Sphinx文档中,当我在重组文本中引用它们时,我想显示键盘键的图片.

例如,如果我说:点击Enter键.我想在线显示Enter键的图片,而不是单词Enter.

我在许多教程中都看到过这种图形,用于引用键盘按键,菜单选项等.他们是如何做到这一点的？我可以在Sphinx中这样做吗？

Azure Private DNS Zone我正在使用和自动化一些流程Private Endpoint。我遇到过 私有 DNS 区域组资源。该资源有一个 Rest API，位于此处。但我在互联网上找不到任何解释其功能的文档。也没有，我在门户网站上找不到它。

对它的功能有什么了解吗？