Sandcastle has a fairly complex XML MAML for generating Conceptual Help, as discussed in a nice intro from 2007. How does this compare to Doxygen in terms of ease of writing content and control over generation of the pages?
I am a big fan of using the Doxygen page facility to write such conceptual help including discussions of design issues. It is much less structured - there's the main page and you can then choose how you group pages by adding links with subpage or ref commands.
I also like the fact I can include casual Graphviz diagrams in my doxygen pages either with inline fragments or referring to an external file.
Related
I am using libHaru (by including the source in my C++ code) to generate PDF files. I am hoping to make these PDF files accessible by adding "tags" (aka "structure tags"). From what I can see in the documentation and source code, libHaru does not support this. Can someone confirm that libHaru indeed does not support tags? And if it's not supported directly, I wonder if there is a way to add tags by modifying the libHaru code? Has anybody done this?
I looked through the 22 page manual for libHaru, and there was no mention of tags, so I think it's safe to assume that it doesn't support tagging.
Attempting to make any library tag PDFs (and do it well) would be a non-trivial task. You'd essentially be re-inventing the wheel. Consider the fact that Adobe Acrobat Pro is only just mediocre at tagging PDFs and requires a ton of human intervention to get it right.
There is a product called CommonLook Dynamic that is made for creating accessible PDFs from live data on a webserver, but I can't vouch for it myself. I have used other products from this company, and they've been very good, but they're not at all cheap.
Generally speaking, PDF tagging is often a very complex thing. To make it work with an automated algorithm, the source code formatting has to be perfectly formed and dead simple. If your source material is at all complex or malformed, it won't come out right.
As an example, it's not possible for PDF generation software to do a good job at things like crafting good alt text for images, creating useful PDF metadata, or tagging complex tables. These are things that require human intervention.
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.
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
I have to develop for a small organisation an internal Knowledge Management platform,
enabling the staff to :
get an overview of the organisation, roles, responsibilities ;
share administrative and technical processes ;
write and share articles (mainly about researches) ;
share quickly practical information ;
upload and share documents.
I was really interested in semantic wikis, because they can provide powerful linking between the different articles, writers, documents... and that way enable the workers to browse from a page to a related one smoothly.
However those people are not computer engineers and I am afraid that including semantic data in their articles wouldn't be possible. They need something user friendly and WYSIWYG if possible.
That way :
do you know user-friendly semantic wikis ?
do you know other tools that would enable this powerful browsing, linking automatically related contents ?
Thank you for your advices.
I would recommand the use of the Semantic_MediaWiki MediaWiki extention in combination with
Wiki Editor WYSIWYG Editor.
You can embed the wikieditor (or basically any other WYSIWYG Mediawiki extention by using the following code:
! WYSIWYGField:
| {{{field|WYSIWYGField|input type=textarea|editor=wikieditor}}}
hey everyone, we just added a nightly action to process the entire source tree with doxygen and place the output onto development webserver.
We also already have a sharepoint structure which holds design documents for various modules/projects. Currently, the level at which we are keeping this documentation is relatively high. We discuss structures of modules and talk about the major classes, but never go down to the individual method level. I wanted to bridge that gap by having hyperlinks in the SDS word documents that would point to doxygen output.
I noticed the links look like this:
http://example.com/docs/ProjectName/d4/d98/class_c_reader.html
http://example.com/docs/ProjectName/d4/d16/class_c_stream.html
The part that sketches me out a bit is "d4", "d98" and "d16" strings in the path. If I copy these links and create the hyperlinks, does anyone know if these URLs are guaranteed be preserved in the future. As I said, entire doxygen output gets regenerated nightly.
You can disable the d4/d98 subdirectories by disabling CREATE_SUBDIRS in the doxygen configuration.
Whether the name of the HTML files will stay the same I do not know for sure but from what I have seen when using doxygen it seems so. If you want to know for sure you can always look at the doxygen source.
Probably these links will not stay permanent.
Furthermore, Doxygen has a XML representation of the generated documentation but even this interface resp. the corresponding DSD has been changed with new releases of doxygen. This is quite frustrating, as we had used the XML representation for a similar application with the assumption that the structures would be kept identical with every new release.