After doing some research on the best way to document swift code. I came across Jazzy and how simple it was to implement. So I follow the installation section of the Jazzy Documentation. I run
sudo gem install jazzy
Then I navigate to the root of my project, in the terminal, and run jazzy which creates a folder called "docs" with a website that displays documentation for 1 class. I have 87 classes which I can visibly see jazzy looping through in the terminal output.
I've read the NSHipster Tutorial about documenting code which also links you to the Jazzy Documentation as well as the Markup Formatting Reference. I've documented some code, which Xcode displays correctly in the side pane or right clicking the function or class. So i'm fairly certain that my syntax is correct.
I took some time to compare that 1 file to the another file that isn't being displayed and I don't see anything out of the ordinary with regards to format.
I'm running:
jazzy version: 0.3.2
Xcode version: 7.1
Swift version: 2.1
OS X El Capitan Version: 10.11
My overall question is; Why isn't jazzy producing documentation for all classes and how can I fix this issue?
After reading more about jazzy more in depth I found this important piece of information.
By default, jazzy only documents public declarations. To generate
documentation for declarations with a lower accessibility level
(internal or private), please set the --min-acl flag to internal or
private.
Which is in the trouble shooting portion of the jazzy git hub page
I ran jazzy with the following line to produce the documentation i expected:
jazzy --min-acl private
Note I should read everything before I decided something isn't working right.
To make it even better. Use
jazzy --min-acl internal --skip-undocumented
Explanation :--min-acl internal this will include all functions, classes, structs in your documentary
--skip-undocumented this will ignore all undocumented classes...
Related
In iOS/Xcode projects it's common to use docstrings with Markdown for documenting methods, properties, protocols etc. within one source file.
However, I couldn't find any proper way for documenting a "folder" of files. E.g. I have sorted my app's functionality in different folders ("Xcode groups") and would like to attach some documentation on that level. For example that one folder is responsible for Network authentication, which is represented by more than just one source file.
How can that be achieved in such a way that we can always regenerate the current documentation with a tool such as Jazzy?
Jazzy do not document files based on folder. It creates Apple like documentation, in which left hand side it names file in alphabetically order.
The only thing you need to do generate document is to comment your code properly. Jazzy parse your comment and creates document for it.
Jazzy can be installed by using this command in terminal
[sudo] gem install jazzy
You need to provide minimum access specifier to jazzy
jazzy --min-acl internal
here internal is access specifier, you can provide private if you want include private files for documentation.
jazzy command compiles you code then it creates document for it. Make sure your code compiles before creating document.
Please refer this document:-
https://medium.com/#_kenny/framework-friday-jazzy-c214fb9a5890
I am trying to generate documentation for my Xcode project and I tried Jazzy documentation and Readme.io but I would like to know about Swagger will work like jazzy or not If it is can i know how to install Swagger in my Xcode.
Swagger is a tool for RESTful API. You better stick with Jazzy for documenting Xcode projects.
I'm trying to get ImageMagick to work in my iOS project. Unfortunately everything I have tried so far has not worked.
Cocoapods
The most obvious approach would be to use the cocoapod. Unfortunately after installing the cocoapod there doesn't appear to be anything exposed to swift to import. Maybe I'm missing something obvious and if anyone has any ideas that would be great. Unfortunately the documentation is lacking as far as specific examples go.
Static library - approach #1
The official ImageMagick docs provide some instructions to compile the latest version of ImageMagick and include a static library in your Xcode project. Unfortunately the first step of the instructions requires running a bash script imagemagick_compile.sh which I cannot find. Once again I could be missing something obvious.
Static library - approach #2
After some additional searching I found the ~Claudio guy which the ImageMagick docs mention as the maintainer of the iOS version of ImageMagick. He has a repo with similar instructions as provided by ImageMagick but this repo includes a bash script to compile and generate a static library of ImageMagick. I tried running the script directly ./all.sh 6.8.8-9 but soon realized I hadn't setup a build directory they way his instructions outlined and I got stuck getting libpng installed correctly.
Static library - approach #3
The same repo with the instructions to compile and generate a static library also includes an old sample iOS project with a static library already included for an older version of ImageMagick. This just about worked except the ImageMagick library has a class Timer that clashes with the Timer class provided by Swift4/iOS so I couldn't get my project to compile using this static library of ImageMagick.
ImageMagick iOS Questions on SO
There are a handful of other questions on Stack Overflow that deal with running ImageMagick on iOS so I know other people have done it but nothing very recent. If anyone has any ideas that would be greatly appreciated, thanks!
Un-answered question on how to use ImageMagick on iOS: ImageMagick iOS image Potentially useful comment that includes some of the same links that I provided above.
Someone already using ImageMagick for iOS but gives no details on how it was implemented: ImageMagick circular dstortion on iOS
Un-answered question from someone already using ImageMagick in their app: Ios - ImageMagick - No Image Created after Distortion
More recent question related to warnings using the cocoapod version: iOS: ImageMagick compiler warnings in Xcode
Other questions: https://stackoverflow.com/search?q=imagemagick+ios Unfortunately I haven't found any of these that have helped.
To integrate ImageMagick into iOS you will need to do the following:
Install the library available here https://www.imagemagick.org/download/iOS/
You will need a Swift-Objective-C bridging header that includes:
#import "ImageMagick.h"
#import "MagickWand.h"
You will need to modify any functions that reference Timer to Foundation.Timer, this will resolve any conflicts with the ImageMagick library
You will need to add under Your target > Build Phases > Link Binary With Libraries > "libxml2.tbd".
Hope this helps
I need to get full Clang warnings list. With Descriptions. For iOS.
I've seen just a list of warnings here
Clang Warnings
But there is no description.
Is there any place where i can get full list of Clang warnings with the description?
I realize this is an old question, but a complete list of warnings, along with the text printed for each one, can be found in the Clang Documentation.
(Note: This answer is now outdated.)
There's a neat project that shows the flags alongside their warning messages:
https://github.com/NSHipster/fuckingclangwarnings.com
While these are not comprehensive explanations in all cases, it is very helpful, especially when you want to switch off specific warnings.
The project hasn't been updated in a while and is probably missing a few new warnings. You could also dive into Clang's source code. I haven't worked with it in a while, but I can tell you where to start:
Clone the Clang repository
Browse to /include/clang/Basic/Diagnostic.td. This file includes a couple of other .td files which contain the various warnings, though I'm not sure if all of them are publicly available, and I think their external names are prefixed, depending on their category. I suggest searching for a known warning (or its description) to solve the puzzle.
Another interesting file is /include/clang/Driver/Options.td, which includes the texts you get using the help command, if I recall correctly.
The [current] accepted answer is correct. clang/clang++'s documentation up on the website doesn't necessarily reflect the supported options in the code. As the old phrase goes, "the source code is the documentation" :/..
One thing that will help with finding options is grepping the source code for DiagGroup. For example, the following demonstrates an attempt at grepping for sign-compare, aka -Wsign-compare, using a pared down clang 7.0.1 source checkout:
$ grep --include \*.td -r sign-compare . | grep DiagGroup
tools/clang/include/clang/Basic/DiagnosticGroups.td:def SignCompare : DiagGroup<"sign-compare">;
I tried to document my Swift project in Xcode with HeaderDoc, but are processed only files ".h" and are ignored files ".swift"
This is my swift File:
/// test
///
/// :param: ann blabla
func testFunc( ann: Foo ) { .. }
I run the following in the Terminal:
headerdoc2html -o ~/Desktop/docum Ninja
This is the error:
Documentation will be written to /Users/me/Desktop/docum
HTML output mode.
No valid input files specified.
Usage: headerdoc2html [-dq] [-o <output directory>] <input file(s) or directory>.
iMac:MyApp me$ headerdoc2html -o ~/Desktop/docum Ninja/
Documentation will be written to /Users/me/Desktop/docum
HTML output mode.
DIR Ninja/
======= Parsing Input Files =======
Processing Ninja/Test.m
Skipping. No HeaderDoc comments found.
Processing Ninja/-Bridging-Header.h
Yeah...
As of right now, HeaderDoc cannot convert Swift inline-documentation into HTML files using headerdoc2html. You, and everyone (myself included) will sadly have to wait.
Other options
So the 'big three' iOS code documentation tools are HeaderDoc, AppleDoc, and Doxygen. Sadly, all three do not support Swift. Good news: AppleDoc is coming out with v3.0 relatively soon and the other two may (probably will) also update as well. AppleDoc is open source, so if you are code savvy, you could adapt it to fit your needs (with swift and all that jazz)
EDIT:
I commented on AppleDoc's Github page and got a couple replies. Mainly, on October 16, 2014 apple is having a conference. After this conference, the AppleDoc guys (gals?) will begin adding Swift support to AppleDoc 3.0 and it will be released at some point.
Speaking of Jazz
Jazzy is something out right now (!) and can generate documentation in the form of HTML for Swift (!!) I had a hard time setting it up, and it's format is unorthodox, but if you can't wait for the big three to update, it may just be for you.
good luck with your adventure.
ZR
For documenting Swift frameworks, libraries, & packages, Apple introduced DocC at WWDC 2021 to generate documentation in Xcode and to host on the web. It does not however, generate HTML.It generates a package that can then be exported and hosted on your website. See this video for the basics of generating documentation using DocC. I also found a good article here that helped me get started. This is an Xcode 13 feature, so it is still in Beta as of this writing. For how to host this documentation from the generated .doccarchive package in Xcode, Apple has a video explaining how to do that here although I have heard of people running into some issues with that tool.