swift helpful

• swift-helpful

[[https://melpa.org/#/swift-helpful][file:https://melpa.org/packages/swift-helpful-badge.svg]]

** Overview
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.

** Install and Configuration

*** MELPA

You can install _{swift-helpful} via MELPA by just doing ~M-x package-install RET swift-helpful~.

*** Quelpa

You can install _{swift-helpful} via Quelpa (https://framagit.org/steckerhalter/quelpa):

#+BEGIN_SRC emacs-lisp
(quelpa '(swift-helpful :repo “danielmartin/swift-helpful”
:fetcher github
:files (“.el" "swift-info/.info”)))
#+END_SRC

*** Usage

Main entry point is the _{swift-helpful} command, which should be executed with the point placed in some Swift code.

** Features

*** Contextual information about Swift keywords and attributes

_{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.

[[file:screenshots/import.png]]

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:

[[file:screenshots/dynamicCallable.png]]

*** API documentation coming from Language Server Protocol

_{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.

[[file:screenshots/isExecutableFile.png]]

*** Swift standard library source code

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:

#+BEGIN_SRC emacs-lisp
(setq swift-helpful-stdlib-path “”)
#+END_SRC

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.

[[file:screenshots/dropFirst.png]]
** Development

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}.

*** Installing Dependencies

#+BEGIN_SRC sh
cask install
#+END_SRC

*** Byte-compilation

#+BEGIN_SRC sh
make compile
#+END_SRC

*** Testing

To minimize the chance of regressions, you can run _{swift-helpful} regression test suite after introducing a change:

#+BEGIN_SRC sh
make test
#+END_SRC

If you want to use ert-runner:

#+BEGIN_SRC sh
make test-ert-runner
#+END_SRC

*** Lint Function Documentation

Any good Emacs package should follow some basic style rules regarding its function documentation. To check that:

#+BEGIN_SRC sh
make checkdoc
#+END_SRC

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.

** Acknowledgements

The idea for this package was inspired by helpful.el (https://github.com/Wilfred/helpful).