Yesterday, Dave DeLong answered a question of mine. It wasn't the answer I was looking for, but in the question he mentioned an alternative way of generating doxygen-style documentation for Objective-C.
Before I could really look into it, someone (maybe Dave himself) noticed the answer didn't match the question that well and removed it. *poof* gone was the link to that documentation tool.
I can't remember the name, but I'm fairly certain it's neither HeaderDoc nor Doxygen itself.
Dave, you out there? What was that link again?
I'm clearly not Dave DeLong, but I'd use appledoc, it's pretty darn awesome!
Developer Page quote:
appledoc is command line tool that helps Objective-C developers generate
Apple-like source code documentation
from specially formatted source code
comments. It's designed to take as
readable source code comments as
possible for the input and use
comments as well as surrounding source
code to generate visually appealing
documentation in the form of HTML as
well as fully indexed and browsable
Xcode documentation set. Although
there are several tools that can
create HTML documentation for
Objective-C, all of those know to me
fall short in meeting the minimum of
goals described below.
Human readable source code appledoc is designed to keep source
code comments as readable as possible
even within your source code editor.
Cross references to objects and members Creating cross references to
classes, categories or protocols is
straightforward and automated as much
as possible.
Apple-like source code HTML documentation Generate appealing
HTML documentation with the same style
as Apple's.
Xcode documentation set creation Generate and install fully indexed and
browsable Xcode documentation sets.
Documentation set can also be
automatically installed to Xcode.
Single tool from sorce code to doc set Single tool to drive generation
from source code parsing to
documentation set installation
Easily customizable output appledoc gives you a lot of command
line switches so you can parameterize
output. If this is not enough, you can
change any or all of the template
files to suit your needs.
100% Objective-C implementation The whole appledoc is written in
Objective-C, so you can easily change
it using familiar language and tools.
This also make debugging much simpler
and effective.
Related
I'm part of team working on SDK that is exposed with several programming languages - currently ObjC, C#, ActionScript, Java (Android) and later we'll have even more languages.
We want to have documentation which is made up of two parts:
Human readable documentation
API Reference
There are links between the two parts: from human readable docs we have links to specific classes or methods and from the API reference we may link to a document that explain the context in which the class or method is used.
We are currently use a combination of sphinx for human readable documentation and language specific tools for API such as doxygen or asdoc
I saw in LeapMotion they were able to generate a complete documentation for multiple programming-language (not human language) with cross links between programming-languages.
The Question
Does someone know how to accomplish such documentation system in a way we'll not have to duplicate each change in human readable docs to every language and have cross links between the languages?
I put together the Leap Motion documentation. I use Sphinx to create the package of docs and Breathe, a Sphinx plug-in, to basically import XML files generated by Doxygen into the Sphinx project for the doxygenated API references (C++, C#, Java, and Objective-C). For links from the so-called "human-readable" pages to the API references, I generate RST substitutions from the .tag files which Doxygen will generate for you. Links from the API reference to the "human-readable" pages are normal, relative hyperlinks (which I should add more of).
I use the conditional content features of Sphinx to generate a separate set of docs (both "human-readable" and API) for each programming language. Thus these articles can be customized for each programming language where needed and have the correct code examples for the current language. Because each doc set has the same structure, it isn't hard to switch from one language to another.
I did add some custom JavaScript to the page templates to help switch between languages.
tl;dr: Sphinx, Breathe, Doxygen and a small amount of custom JavaScript.
If you would like to discuss this further, you can post a question to our (Leap Motion) developer forum. I'll see it (Stackoverflow isn't the proper place for an ongoing discussion).
Hi Ido Ran,
Tools which you've specified are best in industry for documentation purpose,I am afraid there is no such tool yet which could provide both human and as well as API reference.Out of all my personal best is doxygen which is slighly of multi-use (human and API)..Hope this helps.
I'd like to use Vim for editing sources and Xcode for all other purposes like managing, debugging etc. I've installed cocoa.vim plugin and it helps with highlighting, but I still need a way to navigate around the code. In java project I used ctags for the purpose, but it doesn't support obj-c.
So the question is: what is the easiest way to generate vi-compatible tags file for Objective-C sources?
I'm the author of the second link that jelera pointed to and must say it is now out of date.
I would follow the advice in the accepted answer of Alternatives to Ctags/Cscope with Objective-c? in order to get full Obj-C parser support in ctags.
If you use tagbar, this post will help get the new ctags binary working with it:
http://bastibe.de/2011-12-04-how-to-make-tagbar-work-with-objective-c.html
This is pretty much the setup I now use.
Xcode 4 has a very nice built-in help/documentation that you can access e.g. by alt-clicking an identifier in the code, or by opening the help panel in the right sidebar. However, this only works for classes and methods provided by Apple. Is there a way to write some kind of documentation comments (e.g. like the Javadoc comments in Java) in your own code to make Xcode display them in those documentation panels?
http://developer.apple.com/library/mac/#documentation/DeveloperTools/Conceptual/HeaderDoc/intro/intro.html
It's maintained by Apple so it should be well supported. I never actually used it, may try it later.
Ok, it looks like there's no good tool really... there are a few different ones, but they're imperfect and difficult to configure. I couldn't get Doxygen or Appledoc to work, and the tool mentioned by Avizzv92 is referred to as "a pile of poo" elsewhere, so I'd rather not try it... :)
Info that I've found:
How do you document your source code in Xcode?
http://wangling.me/2010/07/documentation-set-generation-tool-in-xcode-is-wanted/
http://developer.apple.com/tools/creatingdocsetswithdoxygen.html
http://www.gentlebytes.com/home/appledocapp/
http://lists.apple.com/archives/xcode-users/2011/Apr/msg00238.html
I wish to get a quick feeling for how much “copy and paste” coding we have, there are many tools for C# / Java to check for this type of thing. Are there any such tools that work well with VB.NET?
(I have seen what looks like lots of repeated code, but wish to get some number to help me make a case for sorting it out)
Update on progress.
I have just tried Simian.
It does not seem to be able to produce a nicely formatted report I can sent by email
It does not cope when the names of local variables, or parameters etc may have been changed, e.g it just matches on lines of text being the same.
Clone Doctor does not support VB.NET (only C# and VB 6 and lot of other)
October 2010: VB.net added to langauges supported by CloneDR
Clone Detective for Visual Studio only supports C#
SolidSDD - Source Code Duplication Detector only supports C, C++, C# and Java
DuplicateFinder is open source, but otherwise looks very match like Simian, e.g it just works on lines of text
ConQAT - Continuous Quality Assessment Toolkit seems to have a clone detector that works for VB.NET (not tried it yet)
Gendarme is a bit like FXCop and has a AvoidCodeDuplicatedInSameClassRule rule, this looks very promising, as it avoids the problem of working at the text level. Just tried it, it is the best solution so far, pity it does not search with a greater scope.
Before claiming that this question is a duplicate, please check that the other question addresses VB.NET, as a lot of tools that work well for C# don't work so well for VB.NET. (However it would not surprise me if this question is a real duplicate)
CodeRush 11.2 introduced a new feature called Duplicate Detection and Consolidation (DDC)
http://community.devexpress.com/blogs/markmiller/archive/2011/11/29/duplicate-detection-and-consolidation-in-coderush-for-visual-studio.aspx
Make sure to check out the options for it as well, as you can have it run when so many lines are changed, certainly time has passed, etc.
They've posted some decent videos on the DevExpress site too.
Simian: http://www.redhillconsulting.com.au/products/simian/
[I'm the author of CloneDR ("Clone Doctor").]
CloneDR is parameterized by a full grammar for the programming language in question. So it doesn't just match lines. Rather, it can find clones which are syntactically well-formed, with variations that are more than just identifier changes, regardless of where they stop or start in a line.
The engine on which CloneDR rests, The DMS Software Reengineering Toolkit" is a tool for analyzing large scale systems in any programming language, and uses language descriptions to drive the analysis. DMS has a wide variety of language front ends already available.
Presently it has VBScript and VB6 (as dialects of "Visual Basic"). It doesn't have VB.net, but that would be pretty straightforward to do given the DMS infrastructure and our experience with lots of other languages.
So, CloneDR could do this just fine, with a small bit of effort on our part.
EDIT October 2010: VB.net added as a language CloneDR can process.
Atomiq supports vb.net amongst other languages, and the results are nicely presented.
JetBrains published console tool set Resharper Console Tools to run duplication analysis. Once installed it allows you to do the same analysis as TeamCity does and generate duplicates report locally and even include duplicates search into custom build process with MSBuild. This tool does exactly what you need. More details you can find here at JetBrains blog post
Try Simian:
Simian (Similarity Analyser) identifies duplication in Java, C#, C, C++, COBOL, Ruby, JSP, ASP, HTML, XML, Visual Basic, Groovy source code and even plain text files.
I once saw an impressive demo of Pattern Insight; its CP Miner may be what you’re looking for: http://patterninsight.com/products/cp-miner.php. It seems to be language-independent, though I couldn’t find anything explicit about languages other than C/C++.
Roll up your sleeves and write your own parser to use it with CPD?
See the question for the tools I found.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
Currently the documentation where I work is in a bit of a state. There isn't anywhere near enough of it, and the documentation that does exist is spread out over many word documents making it hard to find anything.
I'm trying to take some initiative and get it improved, and I figure the first thing is to find a better format to write the documentation in:
My thoughts are that the documentation should be structured in a series of short articles (MSDN / Html Help style) and structured in a suitable tree:
It would be good to be able to produce a standalone Html-Help style package to be shipped with the application
As well as being able to produce a MSDN-style website as a reference for those who are too lazy to look at the CD.
Search is of course a must-have
It needs to be at least reasonably easy to update - if there is a 17 step process to update the published documentation then it makes it seem like too much work to do simple changes, and nobody can ever be bothered to update it.
The documentation is technical in nature, and so ideally it would be nice to be able to include generated documentation from things like the Xml documentation embedded in C# code. This is however definitely a side-requirement - currently very little useful Xml documentation exists, its just that in the future I plan to fix that.
For the same reason it is often good to be able to handle things like attachments (code samples etc...) I'm not expecting anything fancy, but this is something I need to bear in mind to make sure that its at least not handled badly.
Are there any projects or languages that are suited to this sort of documentation?
I've had good results with doxygen on my C and C++ projects although it supports many other languages as well. You put the documentation in comments in the code that can be simple or complex HTML markup. It is very easy to update as it is part of the code. You can make building the documents part of your build process. Additional topic that are not strictly API related can be added as separate HTML documents. The version I'm using doesn't support search so you would have to add another product to search these pages. Because it is HTML you can add in code samples, diagrams, etc.
If you use LaTeX you can get all your documentation in great looking PDFs and printed copies, as well as being able to generate html (via latex2html). TeX has the advantage of being all plaintext, too, so you can track/merge it reliably with your favourite revision control system.
We use confluence as our documentation repository. It is fairly easy to have public and private sections, and has a nice WYSIWYG editor. It can handle attachments and can be saved off as PDF documents if you like.
I've used robohelp with good results. it is plain html, but has a generation process that keeps everthing looking consistent. It can be packaged as a .hlp file with the app, or published to the website. Check it out, it is simple so you can get back to doing your job :)
A clean way is to use DocBook. It is easy write and undetstand. It is also easy to parse as XML parsers are standard and other forms of documentation (e.g. from the embedded documentation in comments) can be easily be transformed to this format.
It is straightforward to generate PDF, HTML og other formats from the DocBook source (tools exist for this purpose).
I've started using DokuWiki. Its not exactly what I was originally looking for (I think I was really looking for a CMS), but it does the job and some respects its better than what I originally had in mind (in particular its a wiki - I've not yet gotten as far as publishing this to our customers however so I'm not sure how well thats going to work out)
I'm using the IndexMenu plugin and the Arctic template to get a navigation tree on the left, and if I publish the wiki itself I'll use the discussion plugin to allow users to post feedback.
Currently my method of handling generated content is to use xslt templates to produce dokuwiki syntax, and write that output directrly to files / folders in the "data/pages" folder.