Xcode 8+ source editor extension for Swift editing that will insert a block comment, possibly with some tags.
NOTE: I know about Xcode's own
Add Documentationcommand which does the same thing, but with more knowledge about the code being commented on. This was more of a learning exercise. I also like my style of comments over Xcode's use of '///' everywhere.
The command does a rudimentary scan forward from the cursor, looking for something to comment. If it finds a
func or init expression, it will insert a block comment describing the function definition. It also has
tailored block comments for struct, class, enum and property expressions (var and let). Again, it is
really crude and basic. If it cannot make sense of anything, it will just punt and insert a generic block
comment.
The block comments have Xcode tags (text delimited by '<#' and '#>') which allow one to tab to a tag and start typing to replace the tag with text.
Version 3 includes a completely rewritten parser that is primarily functional in design. It is based on ideas discussed in the excellent videos put out by the POINT•FREE team. You can see the playgrounds they discuss on their Github repo -- in particular see playgrounds 0056 - 0064.
I used their fundamental design but retooled it to work outside of a playground, and I extended it to of course handle Swift parsing. Be aware that when I say it parses Swift, it only does so in the most basic way to uncover the interesting features to include in a block comment. It would take quite some effort to accurately parse the Swift language.
Build the main BlockCommentApp. This will also build the BlockComment.appex extension. Run the app,
and follow the instructions presented to you.
Extension should be available after a restart of Xcode. NOTE: if you are reinstalling or upgrading, probably best to remove the old version first by moving to trash and then emptying the trash.
Place cursor before the entity to document, then select the Block Comment menu command (or assign a key shortcut in
Xcode preferences. There is also a dumb Mark Comment that just inserts
// MARK: - <#Description#>
to insert a horizontal divider and title in the pop-down list of interesting items.
The code parsing takes place in
BlockCommentExtension/SwiftParsing.swift. The code starts with the
fundamental bits and builds on them primarily via the zip and first functions.
The processing of the request from Xcode happens in
BlockCommentExtension/BlockCommentCommand.swift. More general parsing
functions are found in BlockCommentExtension/Parse.swift and
the Parser generic struct is found in BlockCommentExtension/Parser.swift.