在AppCode中编写代码文档
目录
代码文档可以节省大量时间和头痛。另一方面,它也需要付出很多努力来编写和维护它。在本文中,我们将查看可帮助您创建详细且结构良好的代码文档的AppCode功能,并在代码重构后保持更新。
我们将在此处描述的功能可用于Objective-C和Swift。安装AppCode 2021.3获得完整的Swift文档支持。
文档评论
要在代码中添加简单的注释,您可以使用行(⌘/
)和块(⌥⌘/
) 评论:
但是,这些评论不应该用于文档目的。这是您通常会标记不应该编译的代码的方式:
为了获得一致的类,方法和属性的描述,您可以使用文档评论(文档评论)。文档评论具有特殊的语法。在Swift中,有两种可能的方法可以使用它们:
生成文档评论
在AppCode中,您可以快速生成DOC评论:只需键入///
或者/**
,根据您要使用的语法,然后按⏎
:
DOC评论应在您要描述的代码元素的声明之前。评论的内容成为鼠标悬停或按下弹出的文档F1.
:
在为方法或函数添加DOC注释时,AppCode生成文档存根,其中包含所有可用参数和回报
和扔
关键字如果函数/方法抛出或返回任何内容:
格式化文档评论
评论中的文字可以使用标准进行格式降价语法。您可以添加链接,以粗体和斜体突出显示文本,添加标题等等:
除了标准标记外,您还可以使用特定于文档的关键字,例如警告
那笔记
那版本
那也可以看看
, 和别的。只是输入-
,并且AppCode将向您显示所有可能的选项:
您还可以更改文档评论的样式。去首选项|编辑|配色方案|迅速并调整相应节点下标签,值和文本的颜色和效果:
代码文档中的重构
AppCode可帮助您在更改方法/功能签名后使代码文档保持最新。例如,当您使用该方法重命名参数时改名重构(⇧F6
),参数名称在评论中也会更改:
同样,更改签名重构(⌘F6
)当您添加或删除参数或更改其订单时,会影响评论:
渲染视图
您可以以易于阅读的格式查看DOC评论。只需单击“排水沟”中的图标,以在渲染视图和编辑模式之间切换:
默认情况下,所有仅阅读库文件中的文档注释均以渲染格式显示。您可以禁用阅读器模式在编辑器的右上角,将注释显示为代码:
概括
我们希望AppCode的代码生成,自动完成以及我们在这里描述的重构功能将鼓励您创建详细且一致的代码文档。
有关代码文档支持的更多信息,请参阅我们的网络帮助。