Emacs is described as “the extensible, customizable, self-documenting, real-time display editor”. Wouldn’t you like
the same self-documenting experience when you are writing Swift code in Emacs? swift-helpful
is a package that,
using information from swift-mode
, lsp-mode
and swift-info
, is able to answer questions about anything you see
in a Swift program.
While developer tools are typically identifier-centric in the sense that they only show documentation about API,
swift-helpful
also shows official Apple information about keywords, attributes, etc. It’s the perfect company when
you are experimenting with a Swift playground in Emacs and it is equally useful for people just learning the
language, or people that wants to revisit recent language additions. Also, swift-helpful
is decoupled from the
Apple ecosystem, so you can use it on other platforms like Windows or GNU/Linux. It’s also extremely fast, so you can
perfectly use it on resource-constrained platforms like a Raspberry Pi.
You can install swift-helpful
via MELPA by just doing M-x package-install RET swift-helpful
.
You can install swift-helpful
via Quelpa (https://framagit.org/steckerhalter/quelpa):
(quelpa '(swift-helpful :repo "danielmartin/swift-helpful"
:fetcher github
:files ("*.el" "swift-info/*.info")))
Main entry point is the swift-helpful
command, which should be executed with the point placed in some Swift code.
swift-helpful
shows information about any Swift keyword or attribute. Let’s say you see import
in a Swift program
and you want to know more about how importing modules in Swift works. Simply place the point on top of “import” and
invoke swift-helpful
with M-x swift-helpful
. The tool will show you a brief snippet of documentation about Swift
modules. In many cases, the keyword will be highlighted to focus your attention on where it is mentioned in the
documentation. Pressing the “Read more in manual” button opens the Swift manual section in an Info buffer so that you
can read the definitive discussion about that topic.
Information is not only limited to keywords. The Swift programming language is gradually increasing the use of
attributes in the language, so swift-helpful
will also show information about attributes. Let’s say you don’t know
what @dynamicCallable
means, an attribute introduced in Swift 5. Simply place the point in one occurrence of that
attribute and invoke swift-helpful
to read an explanation, this time coming from the official Swift Reference manual:
swift-helpful
also shows documentation about API in the same way your favorite IDE does. It leverages lsp-mode
, if
configured with my specific extension for Swift, lsp-sourcekit
(https://github.com/emacs-lsp/lsp-sourcekit).
Let’s say you want to know more about the isExecutable
method that you see in a source file from the SourceKit-LSP
project. If you invoke swift-helpful
on that symbol, you’ll see information coming from Language Server Protocol,
including the method type signature, its header documentation, and two convenient buttons to search for its definition
or references across the codebase.
If you have a compiled checkout of the Swift standard library, swift-helpful
is able to search it and present you with
implementation source code with almost zero configuration.
There’s only two requirements to use this feature:
- You need to install the ripgrep tool (https://github.com/BurntSushi/ripgrep), a fast directory searcher.
- You need to point
swift-helpful
to your local checkout of the Swift standard library:
(setq swift-helpful-stdlib-path "<Path to a local compiled checkout of the stdlib>")
Let’s say you want to know more about the dropFirst
collection function in Swift. If you ask swift-helpful
about
that, you will be presented with the function implementation from Collection.swift
. All file paths are actual links,
so clicking on them opens the standard library source file, in case you want to explore further.
Development is automated by means of Make (https://www.gnu.org/software/make/) and Cask (https://cask.readthedocs.io), so installing those programs is encouraged before developing swift-helpful
.
cask install
make compile
To minimize the chance of regressions, you can run swift-helpful
regression test suite after introducing a change:
make test
If you want to use ert-runner:
make test-ert-runner
Any good Emacs package should follow some basic style rules regarding its function documentation. To check that:
make checkdoc
See README.md
inside the swift-info
folder to know how to update the documentation after you have modified the documentation source code in Org.
The idea for this package was inspired by helpful.el (https://github.com/Wilfred/helpful).