DEV Community

Adam.S
Adam.S

Posted on • Edited on • Originally published at bas-man.dev

Swift: Deconstruct SPF: Documentation

#swift #beginners #documentation #package

Hi,

I have been working on this project on and off for a bit now. So I thought it was time to go over how we might be able to not only internally document our code, but also to document it at the package level.

References

Some basics

Code commenting 

// denotes a single line code comment.
Enter fullscreen mode Exit fullscreen mode

Package level 

/// Single line Package comment.
Enter fullscreen mode Exit fullscreen mode 
/**
Multi-line Comments.
Are written subString
*/
Enter fullscreen mode Exit fullscreen mode

I would refer you to the sarunw link above for a good and far more in depth write up.

Getting to the documentation with in Xcode

This can simply be done by hovering your mouse over the function declaration and clicking while holding down the ⌥(Option Key)

Example

Swift code Comment
This produces the following popup.

Swift Documentation Popup

Generating Documentation that can be hosted.

There are a few options for this.

  1. Jazzy
  2. Anarchy Sphinx
  3. Swift-doc

I chose to go with Swift-doc since it can be installed using homebrew.

At present I do not need to host any documentation. Therefore I will not be going through that process here today.

Installation 

$ brew install swiftdocorg/formulae/swift-doc
Enter fullscreen mode Exit fullscreen mode

Build the Documentation

From the top level of your project run the following command.

swift doc generate ./Sources/ --module-name <My Module Name> --format html
Enter fullscreen mode Exit fullscreen mode

If you have no public declarations. You can run this modified command.

swift doc generate ./Sources/ --module-name <My Module Name> --format html --minimum-access-level internal
Enter fullscreen mode Exit fullscreen mode

This will generate your html pages in the directory .build/documentation in your projects parent directory.

Viewing the pages.

If you have Python2 installed, using a terminal. Navigate to your projects parent directory.

cd .build/documentation
python -m SimpleHTTPServer 8000
Enter fullscreen mode Exit fullscreen mode

If you are looking for other options, see the link above Run a Local Server for some ideas.

Then simple open your browser at localhost:8000

Main page

Swift Doc1
Mechanism Page

Swift Doc2

GitHub

Swift-Doc already provides a Github Action that you can add to your repo. So go check it out in the links above.

Closing

Thanks for reading.

Top comments (0)

Read next

codemaker2015 profile image

The ultimate guide to Retrieval-Augmented Generation (RAG)

Vishnu Sivan -

arshisaxena26 profile image

Demystifying hashCode() and equals(): The Backbone of Java Hash Collections

Arshi Saxena -

djames profile image

No Designer? No Problem! Craft Logos Effortlessly with Imagine AI Logo Generator

Blog Post -

vignesh_j profile image

Understanding the Data Link and Physical Layers: The Final Step in Mastering OSI Model and Computer Networking

Vignesh J -