Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
Could anyone share the the ways to do the documentation in objective C? Is there any standard way like it is in java?
Good news for all! :D Finally after waiting a long time Apple has introduced a parser comments for our projects. According to the new features in XCode 5:
Project documentation from framework API reference documentation and
structured comments in your own source code are displayed in the quick
help panel and in code completion popover views. Doxygen and HeaderDoc
structured comments are supported formats.
and from the Clang 3.2 release notes:
Clang parses the comments and can detect syntactic and semantic errors
in comments. These warnings are off by default. Pass -Wdocumentation
flag to enable warnings about documentation comments.
If you want to see an example of this new feature I recommend you take a look at the following article: Documentation in Xcode 5
I don't know what IDE you're using but doxygen lets you generate documentation from comments in Objective-C (as well as C, C++, Java, and some others).
If you're using Xcode (just assuming, since you're using Objective-C), there does seem to be some level of integration (not tested by me, just found on Google): http://developer.apple.com/tools/creatingdocsetswithdoxygen.html
The standard way, as #DiegoPalomar suggested, is to use HeaderDoc, Apple's own tool for embedding structured comments in source code.
It comes with Xcode, so no installation required. It comes with a command-line script that generates HTML output of your documentation.
Docs for HeaderDoc:
Introduction
HeaderDoc command-line tool
HeaderDoc markup
Here's an example:
/*!
* Takes in a number and adds 4 to it.
*
* #param myNumber a number of type NSInteger.
*
* #return The number with 4 added to it.
*/
- (NSInteger)addFour:(NSInteger)myNumber {
return myNumber + 4;
}
Big plus: when you alt-click on your documented method, your doc appears in the balloon:
HeaderDoc is open-source too: http://www.opensource.apple.com/source/headerdoc/
I think you're looking for Doxygen.
Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
The task
We'd like to maintain some developer's documentation for our .NET projects with the following criteria:
"Documents", ideally written in Markdown for providing information that's not closely related to a piece of code (like overview, FAQ).
Standard inline comments for code and API documentation. We do thus in form of standard inline (XML) comments on the classes/interfaces (primarily for IntelliSense support, secondarily for being able to generate an API reference) and would like to continue to do like that.
The documentation is contained in what it documents; e.g. if it's an overview of a solution then in the solution, if it's for a project then among the project's files, version controlled in the same way as the code (this is so the docs are close to what they document, so they are less prone for going out of date, and also this was docs are always "at hand").
Ability to auto-generate (from the CI server) a readable, compiled documentation for a whole project, including "documents" and inline comments for APIs.
An example
We've a project that's a component usable within a 3rd party system. For this project we have the following type of documentation:
Overview (what the project does, what are the aims)
Installation instructions
API documentation
Version history
We'd like to enable our developers and other developers to
- read this documentation from the project's source package and
- from a website.
Solutions we've looked at
Using a wiki (we tried Confluence): this is good for "document"-type of documentation (like overview or installation notes), but it lives independently from the project itself. It's another system to maintain and because it's not before one's eyes when doing development it can quickly go out of date. Also it's one more task to somehow integrate auto-generated API documentation into it.
Using Markdown files and storing them along the code: this is simple and documentation is always at hand and close to what it documents; however we somehow need to generate a publishable web package from these files and the source files' inline documentation.
So far doxygen looks like the solution capable of providing all these. Do you agree?
See "How to include custom files in doxygen".
Broadly speaking this is exactly what I am currently doing, and I'm using Doxygen.
However, I'm afraid I know nothing about .NET. The project I'm working on is a Java package, but includes API documentation extracted from the source, user guides, release records and things like deprecations.
The only thing out of our scope and in yours is Installation Guide, but that's really only because the developer only gets to read it after installation.
We have Jenkins CI building the document on every change.
The 'descriptive' text is all written in Markdown which Doxygen handles reasonably well.
Downsides: If you are familiar with the way Doxygen handles grouping of text for source code you may be confused that these commands don't work to group the blocks of text in Markdown. There are a few other specific oddities but you'll probably find most of them if you scan my own questions on the subject (here, here and here)
Upsides: (Things we've found useful that you've not mentioned)
We can also parse the 'doxygen' markup in the Java API to create a javadoc that IDE's such as Eclipse can use. This does mean we have to limit ourselves to javadoc-style command in the API docs but that's not a big limit.
We've included, under doxygen 'build switch', a manual for your developers on how to write the documentation for the manual (OK, this is slightly recursive!). This provides the recommended command subset to use, and whether (according to taste) you want people to use doxygen #subsection or Markdown ## for headings etc.
Hope that helps.
I'd suggest you try it; trialling a sample of each type of document section you need, to see if it will do the whole set of functions you need. Nothing more annoying documenting 90% then finding it won't do the last 10%.
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 7 years ago.
Improve this question
I am looking for something in Objective C that creates an AST out of objective c code that is modifiable. It would also be great if it also implements the visitor pattern for the AST. Basically looking for something like NRefactory is for c#.
Currently I am investigating CLang which is the only thing I have been able to google which looks close to what I want. If anyone with experience CLang can chime in, that would be great.
I am open to paid solutions as well.
Thanks!
A week since your question, and zero responses.
I'd be surprised if you found an ObjectiveC tool that let you parse and transform ObjectiveC code. Such tools are really hard to build in general, and there's
no obvious demand for one in ObjectiveC.
Clang seems like an option for processing ASTs, but it obviously isn't coded in ObjectiveC. I don't have any direct experience, but I understand Clang will parse ObjectiveC and build an AST. I suppose you can modify the AST, but I don't know if you can regenerate ObjectiveC code from that; I hear you can generate C++ code from a Clang AST for a parsed C++ program. (Clang is a tool that was really hard to build; look at its long history).
If Clang won't do, you might consider our DMS Software Reengineering Toolkit. DMS, given an explicit language description will parse, build ASTs for that language, let you inspect/modify the AST procedurally, and/or apply
source-to-source transformations written using the surface syntax of the specified language (in your case, ObjectiveC), and regenerate valid source code in the language, including comments collected during parsing.
DMS has many language descriptions, including C, Java, C++ (including C++11), COBOL, PHP, etc. There isn't presently a description for ObjectiveC, but DMS is designed to make it easy to provide such language description as might be obvious from what we already have. Compared to building the parsing/transformation/prettyprinting machinery (which was all really hard to build!), defining a language front end is a pretty small task.
EDIT June 8, 2012: (9 months after question, no other responses)
DMS now has an ObjectiveC front end. You can see a DMS-generated parse tree for a small ObjectiveC code here: https://stackoverflow.com/a/10749970/120163 Yes, DMS can regenerate valid ObjectiveC source code from such (modified) trees.
This might be helpful...
http://code.google.com/p/objectiveclipse/source/browse/core/org.eclipse.cdt.core/parser/org/eclipse/cdt/internal/core/parser/?r=981ddadee087d6bb6a27260c019df97e6e40f373#parser%2Fast%2Fcomplete
This question already has answers here:
Closed 11 years ago.
Possible Duplicate:
How to do the documentation in objective C?
Is it possible to write class/method documentation in Objective-C in a way that Xcode 4 displays them in the quick help, and/or generates a doc document from it in the style of Apple's own documentation?
Displaying it live - not that I know of.
But as for generating Apple like documentation, the best I have found is appledoc which I've been using for a year now. If accepts a wide range of commenting styles including Javadoc styles and can generate very Apple like documentation which it can also install directly into your Xcode help system.
I don't know if it still works for Xcode 4 but for Xcode 3 you could generate API doc sets using doxygen.
Apple has a set by step guide: Using doxygen to Create Xcode Documentation Sets on how to do it.
There is also the appledoc tool available from GitHub. Makes nice docsets.
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
Over the last year or so I've seen various announcements on the Clojure discussion list and other places about tools for documenting Clojure code. These range from full-on literate programming systems like Marginalia, and the tool being used to create the book "Clojure in Small Pieces" (or even emacs org-mode), to more conventional Javadoc-style solutions like Autodoc, and Javadoc itself which reportedly can be used with Clojure. A google search turns up various others, perhaps a few that deserve more attention, and for sure some that are just personal utilities for generating docs. My question is what are the best documentation tools, and what are their comparative strengths and weaknesses based on your experiences using them? I have not used any documentation tools to date, and am interested in experimenting with one or more.
I really like Marginalia if you want to take something like a literate programming approach. Marginalia traverses your source code, and produces an html formatted version with comments set beside code in a very clear text. Comments can be markdown formatted, making for a very readable final document. When reviewing source code that I've written some time ago, I find Marginalia really helps. Here's an example made from the Marginalia source itself.
Note that this differs from the original literate programming workflow, where you would write a file and source code is generated from that. With Marginalia, you write a regular source code file, and it's the documentation that's pulled out of that. The output is similar to what one might expect from literate programming, but this way you can still expect syntax highlighting in an editor, without any special literate programming support.
It interoperates with Leiningen, and I believe cake, though I haven't tried that myself.
Codox is a more recent documentation generator for Clojure.
Autodoc is an easy place to start and is what Clojure core and Clojure contrib produce.
Easy to use with Maven. I'm not sure if plugins exist for Leiningen or Cake.
If you want to go fully literate you should give org-babel-clojure a look. org-bable is a literate programming extension to the emacs org-mode.
If you want to use nrepl the following should be added to your .emacs:
(defun org-babel-execute:clojure (body params)
"Execute a block of Clojure code with Babel."
(let ((result-plist (nrepl-send-string-sync (org-babel-expand-body:clojure body params) nrepl-buffer-ns))
(result-type (cdr (assoc :result-type params))))
(org-babel-script-escape
(cond ((eq result-type 'value) (plist-get result-plist :value))
((eq result-type 'output) (plist-get result-plist :value))
(t (message "Unknown :results type!"))))))
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.