Recently I had a need for a way to generate documentation for a large Swift application I had written. And went on the hunt for something to do this. As a result I ran across a program called Jazzy… which reads the Xcode project and extracts special “markdown” comments as well as specific bits of code (classes, functions, enum etc.) and assembles this all into a nice HTML document. While experimenting with Jazzy, I discovered a few bugs… but also looked at it and said “Hey, doing this same kind of documention for an Xojo project would be fantastic”
As a result, I have begun writing in Xojo and GUI based alternative to Jazzy (which is a CLI only)
Jazzy requires an active Xcode install to work, my app does not.
So my question to the community is… Is there any interest in an app that could do that?
If so, once I get this first version working, I believe only the portion that scans the source code would need tweaking for syntax differences (DIM vs VAR, SUB/FUNCTION vs FUNC etc) but that the portion that makes the actual output would be 99.99% the same as it is now.
For more information… Google “Jazzy” (by REALM) and there is a good book by Erica Sadun.
Jazzy (and my app) both use a specialized subset of COMMONMARK (although mine might use a bigger subset than Jazzy does)
Cool. Love markdown.
Also check out XojoDoc as another doc generator for comparison.
I think its a good idea Dave. Bizarrely its something Ive been thinking of writing for Xojo on and off for a while.
On a related note, I really wish Xojo would make two small changes to the Notes features of Xojo projects:
- Make sure the content doesnt randomly disappear or change formatting unpredictably (a bug present for years)
- Add basic formatting support to notes. Bold, underline and italic would suffice.
TextArea know only these styles
With the help of some software tools I found with help by some old posts made by Garry Pettet, I have made great progress on this app… It now generates all the correct pieces, and its just a matter of linking them into a proper website/document. Then adding a dynamic (ie. user configurable CSS) to allow full customization of the output asthetics
Again… once I am satisfied that this App works properly dissecting and documenting a Swift/Xcode project, I will be adapting it to work with Xojo project files and syntax. At this point I don’t know if it will be a single app that can do either, or if the differences will be to great and two apps will be required (I’m aiming at the former)
I am trying to decide if I want the one to document Xojo to read Xojo XML projects or VCS style… (Swift project format is closer to VCS)… If I go for XML then the document will be slightly different in it won’t need (or be able) to document which source file it found the information in as it would be a single file… But it will be a week or two before I start on that version.
In the mean time… anyone have enough Swift experience to be able to find kinks, bugs and anomolies? Anything found now will make the Xojo version that much easier to write
There’s also xjDocs by @Paul Messias at https://parkbenchsoftware.com/xjDocs/index.html
I will take a look at both of those of course… but one thing that is “different” is mine will attempt to conform to the CommonMark spec (which is what Apple uses for QuickHelp in Xcode [and my app is compatible with that])…
For the Swift syntax version, document notation will be
- between /** and */ (note double * )
- or single lines beginning with /// (normal line comment is //)
Since Xojo doesn’t support block comments then the Xojo syntax version will support only single line format (but NOT ‘’’ since that might confuse the CommonMark syntax)
I’m adding a few “extensions” including Tables, and the ability to auto document Sub/Function signatures