{"id":15038561,"url":"https://github.com/bradhowes/blockcomment","last_synced_at":"2025-04-09T23:41:20.683Z","repository":{"id":77294413,"uuid":"69760785","full_name":"bradhowes/BlockComment","owner":"bradhowes","description":"Xcode source editor extension for Swift editing that will insert a block comment, possibly with some tags.","archived":false,"fork":false,"pushed_at":"2022-01-22T09:42:18.000Z","size":6999,"stargazers_count":21,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-24T01:35:17.798Z","etag":null,"topics":["blockcomment","comments","swift-editing","swift-language","xcode-extension"],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bradhowes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null},"funding":{"github":"bradhowes"}},"created_at":"2016-10-01T20:01:01.000Z","updated_at":"2022-04-15T05:28:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"5aaaca3b-20d0-44bb-ab4d-7fc9e010bcd6","html_url":"https://github.com/bradhowes/BlockComment","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bradhowes%2FBlockComment","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bradhowes%2FBlockComment/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bradhowes%2FBlockComment/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bradhowes%2FBlockComment/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bradhowes","download_url":"https://codeload.github.com/bradhowes/BlockComment/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248131467,"owners_count":21052819,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockcomment","comments","swift-editing","swift-language","xcode-extension"],"created_at":"2024-09-24T20:38:54.977Z","updated_at":"2025-04-09T23:41:20.654Z","avatar_url":"https://github.com/bradhowes.png","language":"Swift","readme":"[![CI](https://github.com/bradhowes/BlockComment/workflows/CI/badge.svg)](https://github.com/bradhowes/BlockComment)\n[![Swift 5.0](https://img.shields.io/badge/Swift-5.0-orange.svg?style=flat)](https://swift.org)\n[![Xcode](https://img.shields.io/badge/Xcode-extension-green.svg?style=flat)](https://swift.org)\n[![License: MIT](https://img.shields.io/badge/License-MIT-A31F34.svg)](https://opensource.org/licenses/MIT)\n\n# Swocks -- Swift Block Comments\n\nXcode 8+ source editor extension for Swift editing that will insert a block comment, possibly with some tags.\n\n\u003e **NOTE**: I know about Xcode's own `Add Documentation` command which does the same thing, but with more\n\u003e knowledge about the code being commented on. This was more of a learning exercise. I also like my style of\n\u003e comments over Xcode's use of '///' everywhere.\n\n![](https://github.com/bradhowes/BlockComment/blob/main/images/screenshot.gif?raw=true)\n\nThe command does a rudimentary scan forward from the cursor, looking for something to comment. If it finds a\n`func` or `init` expression, it will insert a block comment describing the function definition. It also has\ntailored block comments for `struct`, `class`, `enum` and property expressions (`var` and `let`). Again, it is\nreally crude and basic. If it cannot make sense of anything, it will just punt and insert a generic block\ncomment.\n\nThe block comments have Xcode tags (text delimited by '\u003c#' and '#\u003e') which allow one to tab to a tag and start\ntyping to replace the tag with text.\n\n# Note on Version 3\n\nVersion 3 includes a completely rewritten parser that is primarily functional in design. It is based on ideas discussed in the\nexcellent videos put out by the [POINT•FREE](https://www.pointfree.co) team. You can see the playgrounds they discuss on\ntheir [Github repo](https://github.com/pointfreeco/episode-code-samples) -- in particular see playgrounds 0056 - 0064.\n\nI used their fundamental design but retooled it to work outside of a playground, and I extended it to of course handle Swift\nparsing. Be aware that when I say it parses Swift,\nit only does so in the most basic way to uncover the interesting features to include in a block comment. It would take quite\nsome effort to accurately parse the Swift language.\n\n# To Use\n\nBuild the main `BlockCommentApp`. This will also build the `BlockComment.appex` extension. Run the app,\nand follow the instructions presented to you.\n\n![](https://github.com/bradhowes/BlockComment/blob/main/images/app.png?raw=true)\n\nExtension should be available after a restart of Xcode.  NOTE: if you are reinstalling or upgrading, probably best to remove the old version\n*first* by moving to trash and then emptying the trash.\n\n![](https://github.com/bradhowes/BlockComment/blob/main/images/menu.png?raw=true)\n\nPlace cursor before the entity to document, then select the `Block Comment` menu command (or assign a key shortcut in\nXcode preferences. There is also a dumb `Mark Comment` that just inserts\n\n```\n// MARK: - \u003c#Description#\u003e\n```\n\nto insert a horizontal divider and title in the pop-down list of interesting items.\n\n![](https://github.com/bradhowes/BlockComment/blob/main/images/mark.png?raw=true)\n\n\n# Code\n\nThe code parsing takes place in\n[BlockCommentExtension/SwiftParsing.swift](https://github.com/bradhowes/BlockComment/blob/main/BlockCommentExtension/SwiftParsing.swift). The code starts with the\nfundamental bits and builds on them primarily via the `zip` and `first` functions.\nThe processing of the request from Xcode happens in\n[BlockCommentExtension/BlockCommentCommand.swift](https://github.com/bradhowes/BlockComment/blob/main/BlockCommentExtension/BlockCommentCommand.swift). More general parsing\nfunctions are found in [BlockCommentExtension/Parse.swift](https://github.com/bradhowes/BlockComment/blob/main/BlockCommentExtension/Parse.swift) and\nthe Parser generic struct is found in [BlockCommentExtension/Parser.swift](https://github.com/bradhowes/BlockComment/blob/main/BlockCommentExtension/Parser.swift).\n","funding_links":["https://github.com/sponsors/bradhowes"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbradhowes%2Fblockcomment","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbradhowes%2Fblockcomment","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbradhowes%2Fblockcomment/lists"}