Is there any free decent program to do code documentation for java?It's hard enough to get the coding project done and then need to spend time writing documentation as well.If you know, please tell me.
javadoc is the standard tool (included with the JDK) for Java source code documentation.
The standard Java API documentation has been generated with javadoc.
Well,
definitely there is javadoc. I think it is by far the most used tool for documenting java projects. Also, take into account that not only documents the methods and the classes but also you can document/create tutorials with static html pages and they'll appear in the generated documentation.
All the most popular IDEs (Eclipse, NetBeans for example) would generate the javadocs for you. It would list all the parameter, thrown exceptions etc. For obvious-purpose methods like getters and setters it will also generate good enough comments (getX() "Gets x" etc.). What you'll need to do than is to complete the javadoc comments for the classes and methods that are more sophisticated than getters, setters or default constructors.
There is also plenty of plugins (for Eclipse see here) that you can use for example to generate UML diagrams to illustrate your code structure.
Javadoc (as noted) is the standard tool for Java. However you may want to check out Doxygen, which will provide more powerful code navigation features and rendering options.
Automatically generated documentation sucks. Why have it? it doesn't add any value.
For years (more than a decade) I am using TallTree's DocJet (http://www.talltree.com/) to generate technical documentation from my Java/C++ code with very satisfactory results. The tool does not require any special tags (although it understands javadoc tags); it sufficient to describe class/method/field in plain English with occasional wording such as 'return' (or any other expression with the same meaning), "parameter" or "argument" and so on.
Related
Is there any tool that allows you to "query" (rather than simply search) the JDK documentation? For example:
Show me all deprecated methods.
Show me all subclasses of a particular class (rather than only the direct subclasses, which the documentation provides).
Show me all methods that return (say) a Thread.
Show me all instances of a given method name, regardless of signature.
What prompted this question is that I was muddling up two completely unrelated methods that I only use occasionally: Pattern.matches() and Matcher.matches(). And then I found that there is also PathMatcher.matches(), which also has a completely unrelated purpose. And that got me wondering how many other "matches()" methods there are in the JDK. And then I thought that there may be other useful queries that could also be run against the JDK documentation.
The only motivation for having such a tool is to help me improve my own knowledge of Java with information that is interesting or useful (to me at least), but is not otherwise easy to obtain. This question is similar, but I am looking for something more sophisticated than a simple search.
ETA: Marcel's suggestion below of using the Doclet API provides a great solution, without too much effort.
ETA2: Re determining deprecated methods, I've just found out that Oracle already address this in the JavaDoc API here
Could it be that you're approaching this from the wrong angle? Rather than parsing the docs, which is an already transformed representation of the source, why not parse source code or byte code of the JDK directly?
parsing byte code
parsing source code
hook into the Javadoc tool (i.e. let Javadoc parse the code for you) by using the Doclet API
Depending on your needs you might also want to take the really easy road and have your classpath scanned by the reflections library.
Reflections reflections = new Reflections("some.package");
Set<Method> voidMethods = reflections.getMethodsReturn(Thread.class);
That having said don't forget that any good IDE can dig up a lot of the info you seem to be looking for (e.g. searching for methods called matches).
It is possible to access bits of MATLAB's internal java code to programmatically change MATLAB itself. For example, you can programmatically open a document in the editor using
editorServices = com.mathworks.mlservices.MLEditorServices;
editorServices.newDocument() %older versions of MATLAB seem to use new()
You can see the method signatures (but not what they do) using methodsview.
methodsview(com.mathworks.mlservices.MLEditorServices)
I have a few related questions about using these Java methods.
Firstly, is there any documentation on these things (either from the Mathworks or otherwise)?
Secondly, how do you find out what methods are available? The ones I've come across appear to be contained in JAR files in matlabroot\java\jar, but I'm not sure what the best way to inspect a JAR file is.
Thirdly, are there functions for inspecting the classes, other than methodsview?
Finally, are there any really useful methods that anyone has found?
There is no official documentation nor support for these classes. Moreover, these classes and internal methods represent internal implementation that may change without notice in any future Matlab release. This said, you can use my uiinspect and checkClass utilities to investigate the internal methods, properties and static fields. These utilities use Java reflection to do their job, something which is also done by the built-in methodsview function (I believe my utilities are far more powerful, though). In this respect, I believe we are not crossing the line of reverse-engineering which may violate Matlab's license.
If you are looking for documentation, then my UndocumentedMatlab.com website has plenty of relevant resources, and more is added on a regular basis so keep tuned.
I am also working on a book that will present a very detailed overview of all these internal classes, among other undocumented stuff - I hope to have publication news later this year.
I am an eclipse fan. If you use that as your IDE, the jar can be imported into one of your projects and you can inspect the methods in there.
To find out more about java objects, I use uiinspect.
The only place I know that is documenting the Matlab hidden Java stuff is Undocumented Matlab by Yair Altman. His site lists plenty of very useful tricks. Being able to use Java to format text in list boxes has come in very handy for me, for example.
EDIT
The man has spoken. Listen to him, since I don't think there's anyone outside MathWorks who knows more about Matlab's internal java code.
Undocumented Matlab is a great place to start looking.
Are there similar documentation generation systems like Javadoc, for C++? Javadoc produces nice output; It would be great if you could use something like it in other languages.
There are several tools that works like JavaDoc for C++ The most popular tool is probably doxygen. It can handle JavaDoc-like comments, and also several languages (e.g., C++, C, Java, Objective-C, Python, PHP, C#). It has pretty good support for tweaking the style of the HTML output using CSS (see the users list for example documentations).
Two important issues when choosing the documentation system is to make sure that it allows you to
Document the entities that you are interested in. Do you want to document the system following the code structure or according to some other module division.
Getting the output formatted as you want. It is preferable when the documentation fits in with your general project style.
Our experience with doxygen is that it is pretty easy to set up and use, and the resulting output is fairly easy to tweak. Unfortunately, doxygen is not perfect, so in some cases it is necessary to work around quirks or bugs where the doxygen parser breaks down. Be sure to inspect all of your generated documentation carefully.
You can't use javadoc specifically, but there are a couple of tools that do what you want. The one most people tend to use is Doxygen. Here are some links for Doxygen and Doc++:
Doxygen
Doc++
There's doxygen that supports a lot of things (and more) Doxygen
There is also qdoc for QT based C++ projects. http://doc-snapshot.qt-project.org/qdoc
I'm just starting to use Sphinx for my Python projects. Its home page states "C/C++ is already supported as well".
It uses a lightweight markup called "reStructuredText".
I've just started using it for my Python projects, and like the look of the output very much.
From the Standardese home page:
Standardese aims to be a nextgen Doxygen.
It consists of two parts: a library and a tool.
The library aims at becoming the documentation frontend
that can be easily extended and customized. It parses C++
code with the help of libclang and provides access to it.
The tool drives the library to generate documentation
for user-specified files. It supports a couple of output
formats including Markdown and HTML as well as
experimental Latex and Man pages.
The Standardese code repository
also points to some blog posts:
Standardese - a (work-in-progress) nextgen Doxygen
Standardese documentation generator version 0.1
Standardese documentation generator version 0.2: Entity linking, index generation & more
Standardese documentation generator version 0.3: Groups, inline documentation, template mode & more
Standardese Documentation Generator: Post Mortem and My Open-Source Future
Question from a C-guy who has to work with some java code that is connected to my C-code via JNI.
I have to work on the build-system, and I'm trying to change that from a shell-script to a proper makefile. For the C-part that's easy, but the java side somehow involves xdoclet stuff.
I haven't yet found out what xdoclet is all about, and I want to understand it all.
I did my Google research, but I have no idea what that thing does. For me it seems like you only have a chance to understand the official documentation if you're already familiar with the problem and you have 10 years of java work under your belt.
Could you please - for dummies - explain what does xdoclet does?
Btw - also I've mentioned C. I'm into object oriented programming as well. There is no need to explain the basics of classes or inheritance (if required to understand xdoclet) to me.
Edit: It's been for IT things roughly a decade ago that I've asked this question. I still have no idea what xdoclet is, but the question got over a thousand views. I would like to see some java guy to chime in and finally clear things up.
The 10000 foot view of XDoclet is that it's a code generation engine. IMO, the interesting thing about XDoclet is how it does what it does, as opposed to what it does.
There is a tool called javadoc that takes annotation in source code comments and generates html documentation with it. This is the classic example of what javadoc was originally designed to produce. In an effort to support different output formats, the authors of javadoc made it plugable -- you can write "doclets" that plugin into the javadoc engine. This allows them to leverage the same source code parser, and emit different documentation output.
XDoclet is a clever hack that uses this engine to do code generation instead of documentation generation.
An example of usage would be: the developer manually writes a class that contains business logic, adds a few xdoclet annotations to the javadoc, and xdoclet generates additional code that provides transactional integrity.
EDIT:
As erickson notes, Java 5 added support for annotations as a language feature that can be processed directly by the compiler. As a result, the functionality that XDoclet used to provide can now be performed directly by the Annotation Processing Tool (apt) that ships with the JDK. Because of this XDoclet is now generally considered to be obsolete.
I'm looking for a tool that will reverse engineer Java into a sequence diagram BUT also provides the ability to filter out calls to certain libraries.
For example, the Netbeans IDE does a fantastic job of this but it includes all calls to String or Integer which clutter up the diagram to the point it is unusable.
Any help is greatly appreciated!!!!!!!
I think jtracert is what you are looking for. It generates a sequence diagram from a running Java program. Also, because its output is a text description of the diagram (in the formats of several popular SD tools), you can use grep to filter for only the classes you are interested in.
I believe the perfect tool to solve your problem is Diver: Dynamic Interactive Views For Reverse Engineering. It provides both static and dynamic sequence diagrams and looks to solve all your requirements from your question.
It is a plugin for Eclipse and lets you:
Easily trace your Java programs
Visualize your program’s runtime functionality
Filter your traces to make them more compact
Filter your IDE based on what occurs at runtime
See what code ran in your source code editors
It's on Github and there is also a project web site
Full Disclosure: I am the current project lead for Diver
Try MaintainJ. MaintainJ generates sequence diagrams at runtime for a use case. It provides multiple ways to filter out unwanted calls. Yes, filtering out unwanted calls is the most important feature needed in sequence diagram generating tools. Besides, MaintainJ provides a neat interface to explore the diagram and search for calls in one use case or across use cases.
Check the demo video to get a quick overview.
I am the author of MaintainJ, by the way.
JTracert is now discontinued. In place, they recommend http://www.jsonde.com/
I have a tool that meets your requirements exactly. Check it out
http://sourceforge.net/projects/javacalltracer/
In addition to being a reverse engineering tool for java it is also very lightweight. You can control the what you want to record from your java program.
Enterprise architect from Sparx claims to be able to reverse engineer java code including generating sequence diagrams - see this section of the user guide
It looks like it can record a debugging session and then you generate the sequence diagram from that
I've not tried it (though have used EA as a modelling tool) so ymmv!
There is a free 30day evaluation download available
Take a look at http://www.maintainj.com
It don't know, whether it can filter library calls, but it has a reasonable graphical front end and seems to trace even very large applications.
MaintainJ is really wonderful tool, Recently i was started to use with MaintainJ with my application it is giving more comfort with my entire usage to understand my system based on Maintainj sequence & UML diagrams.
I am sure for the above question MaintainJ is will give better idea.
Thanks,
Krishna MM
I have just started using the sequence diagram recording feature in Sparx Systems Enterprise Architect. It works very well for C#. You can create filters by class and by method. I'm actually trying to find out if it's possible to filter out an entire package. There is a checkbox for automatically excluding external modules (like the .NET Framework) which aids in declutter. YMMV for Java, but I think their support (and documentation) for Java is generally better (more examples) than for .NET.
Heatlamp (http://www.jmolly.com/heatlamp/) was designed for exactly this purpose.
It generates interactive (and printable) diagrams from running Java code. You can specify filters to describe which classes, packages, and methods to trace. You can also search, filter, and collapse invocations after the diagram is rendered to further reduce the sequence diagram.
Disclaimer: I'm the author of Heatlamp.
This looks like a really nice tool:
http://www.architexa.com/learn-more/sequence-diagrams
But it looks like it's only free for a year, then its $250 a year. Bummer.
I found the ModelGoon plugin to be helpful. It's a bit limited because you choose a single method as the starting point for the sequence diagram, and it only shows the calls that method makes (so to go a level deeper you need to generate another diagram.)
http://www.modelgoon.org/?page_id=53
JIVE (www.cse.buffalo.edu/jive) will construct a sequence diagram from the execution of a Java program. It has an Exclusion Filter capability will allow you to exclude objects belonging to designated classes or packages. JIVE can draw sequence diagrams for multi-threaded Java program execution. It also has the ability compact large diagrams in both the horizontal and vertical dimension, under user guidance.
Here's and add-on to Asgeir's answer. Here's the link that I found.
http://www.java2s.com/Code/Jar/s/sequence.htm
Run from the command line ... "java -jar sequence.jar" ... this is a Java application with a GUI.
The help section says:
SEQUENCE is a program for producing UML Sequence Diagrams. In contrast to most similar programs you don't actually draw the diagram. Instead you write a textual description of the method calls you want to diagram and the layout is calculated and drawn automatically.
So this tool doesn't reverse engineer anything, but I can see how it might be helpful if you wanted to quickly diagram things from scratch. Looks like it was built in 2002 and I think there are probably better tools out there now.
Here's another similar tool here:
http://sdedit.sourceforge.net/example/index.html