I need to implement a documentation generation solution for my workplace and have narrowed it down to the three mentioned in the title. I have been able to find very little information in the way of formalized comparisons between these solutions, and I'm hoping that those of you with experience in one or more of the above can weigh in:
Here is what I have been able to glean from my initial pass:
HeaderDoc Pros: Consistent with apple's existing docs, compatibility with making apple docsets
HeaderDoc Cons: Difficult to modify behavior, project is not actively worked on, many have switched away from it (meaning there must be something deficient, though I can't quantify it).
Doxygen Pros:
Active support community b/c of wide use base, very customizable, most output types (like latex etc)
Doxygen Cons:
Takes work to make it look/behave consistent with apples docs, compatibility with apple docsets is not as simple
AppleDoc Pros:
Looks consistent with apple's existing docs, compatibility with making apple docsets,
AppleDoc Cons:
Issue with documentation of typedefs, enums, and functions, actively being developed
Does this sound accurate? Our desired solution will have:
Consistent look and feel with apples objective-c class reference
Ability for option-click to pull up documentation reference from within Xcode, and then link to the doc (just like apple's classes)
Smart handling of categories, extensions, and the like (even custom categories of apple's classes)
Ability to create our own reference pages (like this page: Loading… that can include images, and be linkable from generated class references seamlessly, like how apple's UIViewController class reference links to the linked page.
Easy to run command line commands that can be integrated into build scripts
Graceful handling of very large codebase
Based on all of the information above, are any of the above solutions clearly better than the others? Any suggestions or information to add would be extremely appreciated.
As the creator and lead developer of doxygen, let me also provide my perspective
(obviously biased as well ;-)
If you are looking for a 100% faithful replica of Apple's own documentation style, then AppleDoc is a better choice in that respect. With doxygen you'll have a hard time to get that exact same look, so I would not recommend to try.
With respect to Xcode docsets; Apple provides instructions how to set that up with doxygen (written in the time Xcode 3 was released). For Xcode 4 there is also a nice guide how to integrate doxygen.
As of version 1.8.0, doxygen supports Markdown markup, as well a large number of additional markup commands.
With doxygen you can include documentation on the main page (#mainpage) as well as on subpages (using #subpage or #page). Inside a page you can create sections and subsections. In fact, doxygen's user manual was completely written using doxygen. Besides that, you can group classes or functions together (using #defgroup and #ingroup) and inside a class make custom sections (using #name).
Doxygen uses a configuration file as input. You can generate a template with default values using doxygen -g or use a graphical editor to create and edit one. You can also pipe options through doxygen via a script using doxygen - (see question 17 of the FAQ for an example)
Doxygen is not limited to Objective-C, it supports a large range of languages including C, C++, and Java. Doxygen is also not limited to the Mac platform, e.g. it runs on Windows and Linux too. Doxygen's output also supports more than just HTML; you can generate PDF output (via LaTeX) or RTF and man pages.
Doxygen also goes beyond pure documentation; doxygen can create various graphs and diagrams from the source code (see the dot related options). Doxygen can also create a browsable and syntax highlighted version of your code, and cross-reference that with the documentation (see the source browser related options).
Doxygen is very fast for small to medium sized projects (the diagram generation can be slow though, but nowadays runs on multiple CPU cores in parallel and graphs from one run are reused in the next run).
For very large projects (e.g. millions of lines of code) doxygen allows the projects to be split into multiple parts and can then link the parts together as I explained here.
A nice real-life example of using doxygen for Objective-C can be found here.
The development of doxygen highly depends on user feedback. We have an active mailing list for questions and discussions and a bug tracker for both bugs and feature requests.
Most users of doxygen use it for C and C++ code, so naturally these languages have the most mature support and the output is more tuned towards the features and needs for these languages. That said, also wishes for and issues with other languages are taken seriously.
Note that I do nearly all doxygen development and most testing on a Mac myself.
I'm the author of appledoc, so this answer may be biased :) I tried all mentioned generators though (and more) but got frustrated as none produced results I wanted to have (similar goals as you).
According your points (I only mention appledoc and doxygen, I don't recollect headerdoc that well):
Consistent look: appledoc out of the box, other need to tweak css, but probably doable.
Generation of documentation sets (for Xcode references): appledoc full support for searchable and option-clickable documentation out of the box, doxygen generates xml and makefile which you need to invoke yourself. Additionally appledoc supports published docsets out of the box.
Categories: appledoc allows you to merge categories to known classes or leave them separate, foundation & other apple class categories are listed separately in index file. doxygen: this wasn't working best when I tried it.
Custom reference pages: appledoc supports out of the box using either markdown or custom html, doxygen: you can include custom documentation to main page, don't know if you can include more pages.
Easy command line: depends how you look at it: appledoc can take all arguments through command line switches (but also supports optional global and project settings plist files) so it should be very easy to integrate with build scripts. doxygen requires usage of configuration file to setup all parameters.
Large codebases: all tools should support this, although didn't compare timewise. Also not sure if any tool supports cached values (running over previously collected data in order to save some time) - I am looking into adding this for next major release.
It's some time since I tried using other tools, so above mentioned issues with doxygen/headerdoc may have been addressed! appledoc itself also has disadvantages: like you mention there's no support for enums, structs, functions etc (there was some work done in this direction, check this fork), and it has it's own set of issues that may prevent you using it, depending your requirements.
I am currently working on major update that will cover most glaring issues, including support for enums, structs etc. I'm regularly pushing new stuff to experimental branch as soon as I finish larger chunks and make it stable enough, so you can follow the progress. But it's still very early and progress depends on my time so it may take quite a while until working solution.
Xcode 5 will now parse your comments to search for documentation and display it:
You don't have to use appledoc or doxygen anymore (at least when you don't want to export your docs). More information can be found here
Related
I come from the world of JavaDocs and love the DX of working on a thoroughly-annotated application after a certain level of complexity.
Being able to hover over and peek all the props (and implied types) of a component with some brief documentation would save me so much time instead of having to open up and read through the whole component. Better yet, running a command to generate a documentation site just like you can with JavaDocs would be dope!
Are there any standards or tools built around creating SvelteDocs? I looked through the VS Code marketplace and didn't see any documentation tooling related to Svelte.
I stumbled upon this question in search of more in-depth documentation for the hover/peek documentation method I've been using. It seems that it is not very well documented (ironically) but it is a part of Svelte language-tools and I've been using it for some time with Svelte for VS Code so I'm sure there was more documentation at some point. The way it's used is as follows in your component. I remember reading somewhere that it needs to be the first thing in your component, but I can't find that source anymore.
<!--
#component
some markdown here
-->
For some reasons the only documentation I can find of it is here. But it provides very nice markdown support so you can craft some very informative hover/peek documentation for your components.
EDIT:
Still can't locate official documentation for the #component commenting feature but realized it is indeed described in the FAQ: https://svelte.dev/faq#how-do-i-document-my-components Does this information belong in the actual docs? Maybe.
After more digging, I found just a couple projects for documenting Svelte.
SvelteDoc Parser -- takes a VueDoc approach, based on JSDoc standards, generates JSON documentation for Svelte components
Svelte-Docs -- documentation in Markdown mixed with Svelte's features, can embed components in the generated doc pages
Both look interesting while taking completely separate approaches to solving the issue of application documentation. Perhaps there's still room to build a CLI-based site generator for the SvelteDoc Parser which could be turned into a VS Code plugin!
It is difficult to find a good one. I recommend
https://github.com/carbon-design-system/sveld
It looks very promising. It offers export in Typescript definitions, JSON and Markdown. In my opinion there is only one critical bug left (Markdown generation) so hopefully it can be used very soon.
I recently stumbled upon the Doxygen Documentation Generator for C++ and especially Qt Code. It generates Documentations in different formats (html, pdf, ...) and includes stuff like Model-Flow-Diagrams. The documentation primitives are used directly in the code, instead of maintaing it seperatly (like in the NetLogo Info Tab). Unfortunately, doxygen does not support Netlogo Models. Do you know any similar tools or extensions for automatic Documentation creation with Netlogo files?
If such a thing existed, it would almost certainly be listed at http://ccl.northwestern.edu/netlogo/resources.shtml .
Can't be 100% sure no such thing exists, but 90%+ sure.
I am porting doxygen documentation from visual studio c# project to java eclipse project.
Can you please suggest tutorials or some guides for mapping the one style of comments
to the other?
For example, how do I translate this doxygen comment to javadoc comment?
/// the custom solution data type, derived from Solution
Thanks
Speaking from the perspective of one who has tried to map from doxygen (in C) to javadoc I think you will find this direction remarkably difficult, especially if you have much narrative in your original commentary. I find javadoc dreadfully lacking in most of the capabilities of doxygen, so really only the absolute minimum commentary can be usefully transferred - things like #param, #return etc. I've never found any good tutorials, or even any bad ones. I suspect this isn't something people do by choice.
Consider whether you could continue to use doxygen. Doxygen interprets all the javadoc commands (at least all the ones I've come across), and you can benignly add doxygen '\'-style commands into the java commentary without upsetting any existing javadoc processing.
Edit: Just to clarify that point slightly. Javadoc won't have warnings or errors as a result of using \command entries, but the \command text will emerge in the javadoc output as text.
The downside, of course, is that javadoc is needed if you want pop-ups in your IDE (e.g. Eclipse) so if that's a requirement then using doxygen instead won't be much use. However, if you just need to create good quality HTML documentation / manuals with diagrams and narrative then it might be an option.
Given a project I'm about to start there will be documentation produced.
What is the best practice for this?
Should the documents live with the code and assets or should there be a separate documentation store?
Edit
I'd like a wiki but I will need to print the documents etc... It's a university project.
It really depends on your team. Where I work, we keep documentation in a wiki which is linked in with our team website. For the purposes of shipping documentation, the wiki can be exported and we run it through a parser that "fancifies" the look and feel of the documentation for customer purposes.
Storing the documentation with the code (typically in your source repository) is not a bad idea. Just make sure to keep them separated. For example, keep a docs folder which is on the same level with your src folder in your repository. This way, you can quickly ship the current documentation, you can easily track revisions, and anybody new to the project can immediately jump in without having to go to multiple locations for information.
Storing it in source control is fine.
This is an interesting question -- basically, what others are saying is right about generated documentation, source files and templates/etc. should be stored in source control and generated during your build process.
As far as requirements/specs/etc. documentation, I have worked both ways, and I very much prefer using SharePoint or a Wiki/document portal that is designed for document sharing/versioning. The reason is, most non-developer folks aren't comfortable working with source control systems, and you don't gain any of the advantages of intelligent merging if you are using a binary format like Word. Plus it's nice to have internet-based access so you can reference and work on the docs in a distributed team without people having to install extra software.
Here's a 2017 summary of the options and my experience:
(extreme 1) Completely external (e.g. a wiki, Google Docs, LaTeX, MS Word, MS Onedrive)
People aren't bothered about keeping it up to date (half of them don't even know where to find the page that needs updating since it's so out of the trenches).
wiki platforms are “captive user interfaces” - your data gets stored in their proprietary schemas and is not easy to examine with a simple text editor (Confluence is even worse in that you have no access to the plaintext content at all anymore)
(extreme 2) Completely internal (e.g. javadoc)
pollutes the source code, and is usually too low level to be of any use. Well-written source code is still the best form of low level documentation.
However, I feel package-info.java files are underutilized.
(balance) Colocated documentation (e.g. README.md)
A good half way solution, with the benefits of version control. If a single README.md file is not enough, consider a doc/ folder. The only drawback of this I've seen is whether to source control helpful graphics (e.g. png files) and risk bloating the repo.
One interesting way to avoid this problem is to use plaintext diagram tools (I find Grapheasy and Text Diagram to be a breath of fresh air).
plaintext can be easily read even if your rendering engine changes as the years go by.
Github's success is in no small part thanks to its README.md located in the root of the project.
One tiny disadvantage of this approach though is that your continuous integration system will trigger a new build each time you make edits to the README.md file.
If you are writing versioned user documentation associated with each release of the product, then it makes sense to put the documentation in source control along with its associated product release.
If you are writing internal developer documentation, use automated internal source code documentation (javadoc, doxygen, .net annotations, etc) for source level documentation and a project wiki for design level documentation.
I think most of us in the industry are not really following best-practices and it of course also depends a lot on your situation.
In an agile environment where you would have a very iterative process of release, you will want to "travel light". In this particular case, Jason's suggestion of a separate Wiki really works great.
In a water-fall/big bang model, you will have a better opportunity to have a decent documentation update with each new release. Also you will need to clearly document what version of the requirements was agreed on and have loads of documentation for every tiny change you do to requirements (due to the effects it has on subsequent stages). Often if the documentation can live together with the version controlled source code it is the best.
Are you using any sort of auto-documentation or is it completely manual? Assuming that you are using an auto-documentation system, the documentation is more or less generated on the fly, and would be part of the code itself.
To me, (assuming that it's possible with whatever code you are using), this would be the preferred method of handling it, as you wouldn't need to maintain the documentation source at all.
Right now, I'm particularly interested in reading the data from MP3 files (ID3 tags?), but the more it can do (eg EXIF from images?) the better without compromising the ID3 tag reading abilities.
I'm interested in making a script that goes through my media (right now, my music files) and makes sure the file name and directory path correspond to the file's metadata and then create a log of mismatched files so I can check to see which is accurate and make the proper changes. I'm thinking Ruby or Python (see a related question specifically for Python) would be best for this, but I'm open to using any language really (and would actually probably prefer an application language like C, C++, Java, C# in case this project goes off).
There is a great post on using PowerShell and TagLibSharp on Joel "Jaykul" Bennet's site. You could use TagLibSharp to read the metatdata with any .NET based language, but PowerShell is quite appropriate for what you are trying to do.
use exiftool (it supports ID3 too). written in perl, but can also be used from the command line. it has a compiled windows and mac version.
it is light-years ahead of any other metadata tool, supporting almost all known audio, video and image files, supports writing (not just reading), and knows about all the custom/extended tags used by software (such as photoshop) and hardware (many camera manufacturers).
#Thomas Owens PowerShell is now part of the Common Engineering Criteria (as of Microsoft's 2009 Product Line) and starting with Serve 2008 is included as a feature. It stands as much of a chance to be installed as Python or Ruby. You also mentioned that you were willing to go to C#, which could use TagLibSharp. Or you could use IronPython...
#Thomas Owens TagLibSharp is a nice library to use. I always lean to PowerShell first, one to promote the language, and two because it is spreading fast in the Microsoft domain. I have nothing against using other languages, I just lean towards what I know and like. :) Good luck with your project.
Further to Anon's answer - exiftool is very powerful and supports a huge range of file types, not just images, but video, audio and numerous document formats.
A Ruby interface for exiftool is available in the form of the mini_exiftool gem
see http://miniexiftool.rubyforge.org/