Xcode8下的文档注释插件
前言
苹果在 Xcode8 以后已经不支持第三方插件了,但是他又开放了一个专门制作插件的东西: Xcode Source Editor Extention,所以现在只能这个来制作 Xcode 插件了.
创建Xcode Source Editor Extention
1.新建一个项目
首先我们先新建一个 Mac 下的 app, 因为我们是创建 Extention ,所以我们不关心这个 app 具体实现.
Paste_Image.png
Snip20160930_3.png
2.我们新建一个 target
Paste_Image.png
选择Xcode Source Editor Extention
Paste_Image.png
Paste_Image.png
选择 Activate
Paste_Image.png
完成后文件结构如下
Paste_Image.png
3.介绍插件的 info.plist
在 info.plist 里面我们需要关注是 NSExtention 这个字段
Paste_Image.png
XCSourceEditorExtensionPrincipalClass: 这个字段表示的是插件的类名, 他必须与遵守了XCSourceEditorExtendsion 协议的类一致,而且每个插件仅有一个这样的类
XCSourceEditorCommandDefinitions: 这个数组表示的是插件里面有几个命令,每一个元素是一个命令. 如果有多个命令的话,直接往这个数组里面添加元素就好.
XCSourceEditorCommandClassName: 命令所对应的类名,这个类需要遵守 XCSourceEditorCommand 协议
XCSourceEditorCommandIdentifier: 命令的标识
XCSourceEditorCommandName: 这个是命令在 Xcode 里显示的名字,可以随便写,无所谓
我在项目里创建了两个命令,一个普通的注释,一个是文档注释.
Paste_Image.png
4.运行插件
运行前,需要对项目和 target 都进行签名
Paste_Image.png
Paste_Image.png
编辑 target 的scheme, 在 info 的Executable 里面选择 Xcode8
Paste_Image.png
运行后会出现一个灰色图标的 Xcode , 这个就是测试用的 Xcode 了,我们可以在这个Xcode 里面的 Editor选项卡里的最后找到我们的插件(必须选中某个文件才会出现). 如果没有找到或者无法点击插件, 重新运行就好了. 注意不要用灰色图标的 Xcode 再次运行新, 可能会出现为知的错误和问题.
Paste_Image.png
Snip20160930_20.png
我们还可以为每一个命令添加一个快捷键, 只要在设置快捷键的地方找到我们的命令就好了
Paste_Image.png
5.安装插件
选择我们创建的 app, 运行, 然后重启 Xcode 就好了
Snip20160930_29.png
XCSourceEditorExtendsion协议
一共两个方法和一个结构体
Paste_Image.png
extensionDidFinishLaunching: 插件加载后会调用,此时命令还没有被执行,也不会获取任何信息
commandDefinition: 这个方法会返回一个数组,也就是 info.plist 里面的XCSourceEditorCommandDefinitions字段对应的那个数组
XCSourceEditorCommand 协议
一个方法和一个类
Paste_Image.png
当我们执行我们的命令时, 系统会把当前我们选中的文件里面的所有文本信息包裹到 invocation 里传给我们
completionHandler: 这个 block 应该在我们做完处理后或者是发生错误时调用. 如果把一个错误传给这个 block, 那么系统就会有一个提示.
invocation 是一个 XCSourceEditorCommandInvocation 的实例, 它buffer 属性里有我们需要处理的数据; cancellationHandler属性是当用户取消了正在执行的命令会调用的 block.
XCSourceTextBuffer
我们要操作的所有文本数据都在这里,我主要介绍 lines 和 selections 这个两个属性
Paste_Image.png
lines
系统会把当前文件的每一行字符串存进这个数组, 我们可以通过下标取到对应的那一行字符串, 然后就可以进行操作了
selections
这个数组里存的是我们选中的行, 但是它并不是把每一行字符串存进数组, 而是专门存了XCSourceTextRange类型的元素. 一般情况下, 这个数组里只有一个元素.
Paste_Image.png
XCSourceTextRange中的 start 属性是我们选中的开始索引, 包括行索引(line)和列索引(column).
XCSourceTextRange中的 end 属性是我们选中的结束索引.
当我们拿到开始的行索引和结束的行索引后, 我们就可以去 lines 里面取到对应的那一行的字符串了.
至此, 关于苹果文档里东西已经介绍完了, 剩下的就是在遵守了XCSourceEditorCommand协议的类里去写逻辑代码, 进行相关的操作, 我就不啰嗦了, 大家可以去 github 上看我的源码
关于选择多行并给每一个方法或属性添加文档注释的思路
添加文档注释, 实际就是给 lines 这个数组插入数据, 但是因为数组在插入数据后, 索引会变化, 所以不能够用selections里面的那个行索引来取值.
我的办法是给一个中间变量, addLineCount, 来记录我们插入了多少行数据, 然后我们从selections中去到的行索引加上这个值就是真实的索引了.
func perform(with invocation: XCSourceEditorCommandInvocation, completionHandler: @escaping (Error?) -> Void) {
let lines = invocation.buffer.lines
let selections = invocation.buffer.selections
for selection in selections {
if let textRange = selection as? XCSourceTextRange,
textRange.start.line != lines.count {
var lineIndex = 0
if textRange.start.line == textRange.end.line {
lineIndex = textRange.start.line + addLineCount
var line = lines[lineIndex] as! String
if line == "\n" {
lines.removeObject(at: lineIndex)
}
line = lines[lineIndex] as! String
if line.hasVarOrLet() {
insertVarOrLetDoc(at: lineIndex, withLine: line, inLines: lines)
}else if line.hasFuncMethod() {
insertFuncDoc(at: lineIndex, withLine: line, inLines: lines)
}else if line.hasProperty() {
insertPropertyDoc(at: lineIndex, withLine: line, inLines: lines)
}else if line.hasMethod() {
insertMethodDoc(at: lineIndex, withLine: line, inLines: lines)
}
}else {
for index in textRange.start.line...textRange.end.line {
lineIndex = index + addLineCount
let line = lines[lineIndex] as! String
if line.hasVarOrLet() {
insertVarOrLetDoc(at: lineIndex, withLine: line, inLines: lines)
}else if line.hasFuncMethod() {
insertFuncDoc(at: lineIndex, withLine: line, inLines: lines)
}else if line.hasProperty() {
insertPropertyDoc(at: lineIndex, withLine: line, inLines: lines)
}else if line.hasMethod() {
insertMethodDoc(at: lineIndex, withLine: line, inLines: lines)
}
}
}
}
}
completionHandler(nil)
}
每添加一行数据, 就让这个addLineCount加一
func insertFuncDoc(at index: Int, withLine line: String, inLines lines: NSMutableArray) {
var charIndex = line.startIndex
while line[charIndex] == " " {
charIndex = line.index(after: charIndex)
}
let spaceStr = line.substring(to: charIndex)
let prefixDoc = spaceStr + threeCommentStr
if line.funcStrHasReturnValue() {
if hasDoc(at: index-1, withPrefix: prefixDoc + returnsStr, inLines: lines) {
return
}
let returnValueStr = prefixDoc + returnsStr + "<#return value description#>"
lines.insert(returnValueStr, at: index)
lines.insert(prefixDoc, at: index)
addLineCount += 2
}
let paramNames = line.parserFuncStrParameter()
if paramNames.count > 0 {
for paramName in paramNames.reversed() {
if hasDoc(at: index-1, withPrefix: prefixDoc + parameterStr + paramName, inLines: lines) {
return
}
let paramDoc = prefixDoc + parameterStr + paramName + ": " + "<#\(paramName) description#>"
lines.insert(paramDoc, at: index)
}
lines.insert(prefixDoc, at: index)
addLineCount += (paramNames.count + 1)
}
if hasDoc(at: index-1, withPrefix: prefixDoc, inLines: lines) {
return
}
let funcDoc = prefixDoc + spaceChar + descriptionStr
lines.insert(funcDoc, at: index)
addLineCount += 1
}
已经添加过文档注释的, 不会重复添加
func hasDoc(at index: Int, withPrefix prefix: String, inLines lines: NSMutableArray) -> Bool {
if let line = (lines[index] as? String), line.hasPrefix(prefix) {
return true
}
return false
}
ps: 我为何要在苹果已经提供了文档注释功能的情况下还要写这个插件? 我是不会告诉你, 那个功能被我给玩儿崩了.....
Paste_Image.png
