Related
There are a couple mentioned in the documentation but looking through the api, there are tons more processors
The current JavaDoc is indeed lacking in completeness. I find myself in the same situation where I am constantly searching for which abstract processor is the best to use, even though the names of the processors are pretty straight forward.
Currently the only way to exactly know what a processor does and how to use them is to open the source code.
What options are there for enforcing that code is documented? I want something that will run as part of the build process e.g. a maven target that will check that code is documented (class level and method level) and report if any code is missing documentation.
Have looked at FindBugs, PMD, and CheckStyle, but they dont appear to offer this capability.
Well, I hate to tell you this, but useful documentation cannot be enforced using tools.
Checkstyle can check if Javadoc is present, but it cannot check that the Javadoc contains anything other then #param pMyParam the myParam and other meaningless junk. Even if you let some tool check the contents of the docs, this would produce loads of false positives and would lead to simple, but useful comments to be inflated only to please the checking tool. After some time, the developers will learn to filter out Javadocs when reading code like we filter out ads when reading a web page. So, all tooling will gain you nothing if the developers do not want to write good and helpful docs.
To say it with the words of Antoine de Saint-Exupéry: If you want to build a ship, don't drum up people together to collect wood and don't assign them tasks and work, but rather teach them to long for the endless immensity of the sea.
My recommendation is: Use checkstyle to check for the very basics, such as the fact that each class has at least a type comment, and that interfaces document their methods as well. Then, educate the developers where necessary on what makes a meaningful and useful documentation, and make it clear that in the eyes of the development lead, good quality code has good quality docs. Javadocs can be very good even if certain methods are not documented at all. The checking can then only be done by manual inspection, e.g. by peer reviews or some kind of formalized step in the quality control process.
Just my two cents.
Perhaps it is not exactly what you are looking for but you can use Sonar and call it when you compile the code.
Sonar will provide with lots of information included checkstyle
Sonar is very easy to use and integrate with a maven project.
Doc: http://docs.sonarqube.org/display/SONAR/Installing+and+Configuring+Maven
Teamscale can check whether comments are missing. It can also assess the quality of the comments and reveal trivial as well as unrelated comments.
Disclaimer: I am a Teamscale developer.
A while ago there was this doclet from Sun called DocCheck. Creates a report from the javadoc. Don't know if its still available..
Do a google search.
Ok, google search... works with version 1.2, 1.3 and 1.4. Its experimental and appears to be inactive. Is it worth using now? I don't know. That's something for you to decide.
javadoc doccheck download http://192.9.162.55/j2se/javadoc/doccheck/index.html
Ever since I started playing around with Scala, I have had one big question concerning the Java API: why does Oracle keep the same old HTML page with "frameset" tags and no search function at all? It looks like they haven't made it to the Web 2.0...
The Scala API documentation on the other hand, while not the best website in the web history, is several orders of magnitude more usable.
Anyways, if anybody knows why that is and, more importantly, if there exists a Java API documentation with a better interface, please let me know!
Recently, for Java 7, JavaDoc was improved so it could use custom CSS. Here are the first results: http://download.java.net/jdk7/docs/api/. The work continues and I think we'll see more when new updates come out. I do agree that ScalaDoc is superior, but they didn't have to deal with 15 years of legacy.
Javadocs provides the output in that format and its published at that address, I guess no one really saw the need for improvement, but now that you mention it, it makes for an interesting side-project. I googled around to find if there was any "better" interface but no luck.
You could run javadoc -h to see what extra options are available if you want to re-generate the javadocs. Some interesting ones are to provide custom header/footer and linking to the source, but nothing to the effect that you are asking.
Those HTML pages were made using the Javadoc tools, a standard way to build documentation in Java.
I don't know if there are other webpages with a better formatting of the API, but if it helps you with anything, and you are using an IDE and the SDK, you can see the source code for most of the files there.
JavaDoc was designed to be the lowest common denominator. Virtually any web browser can display it, even without JavaScript support.
If you are looking for quicker access and search capabilities, you can access JavaDoc from within an IDE such as Eclipse.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
Questions asking us to recommend or find a tool, library or favorite off-site resource are off-topic for Stack Overflow as they tend to attract opinionated answers and spam. Instead, describe the problem and what has been done so far to solve it.
Closed 9 years ago.
Improve this question
Let's face it: You don't need to be a designer to see that
default Javadoc looks ugly.
There are some resources on the web which offer re-styled Javadoc. But the default behaviour represents the product and should be as reasonably good-looking.
Another problem is the fact that the usability of Javadoc is not up-to-date compared to other similar resources.
Especially huge projects are hard to navigate using Firefox's quick search.
Practical question:
Are there any standalone (desktop) applications which are able to browse
existing Javadoc in a more usable way than a browser would?
I'm thinking about something like Mono's documentation browser.
Theoretical question:
Does anyone know, if there some plans to evolve Javadoc, in a
somehow-standardized way?
EDIT: A useful link to Sun' wiki on this topic.
I have created a Markdown (java) Doclet which will take source comments in Markdown formatted text and create the same HTML Javadocs.
The new doclet also does some restyling on the text, but the HTML generated is not changed at this stage.
That goes some way to address the HTML-in-java-commenting issues which is probably the biggest usability problem with current Javadoc.
I don't think that the concepts of Javadoc are outdated. As far as i can see, these concepts are rooted years ago in a product named doxygen, which is still available for other languages (i.e. Objective-C where it is heavily used). Even this has it's predecessors - have a look at the programming environment used by Donald Knuth to create TeX (Literate programming).
Nevertheless it is a intriguing idea to have a single source for program code and documentation.
Besides of that, the presentation of the documentation can be customized to your special needs using a plug-in system supported by the JavaDoc tool. You might provide a plug-in (as we do) that publishes directly into a database which is directly accessible via web. Using collaborations anyone can provide additional comments or clarifications to the documentation that might find their way back into the original source.
Javadoc is the best source code auto-documentation generation system I've ever seen. Large part of that is that it's so simple - I can browse javadocs even with my 5 year old cell phone if I want to! While I agree that a bit of a facelift could be in order and especially JDK is a pain to browse through, I wouldn't dare reinventing the wheel entirely because what we currently have is a RESTful, easy to use solution for its purpose which works just about anywhere.
I recently got a mail forwarded that Sun is working on modernizing the Javadoc HTML output. From said mail:
We are proposing improvements to javadoc/doclet for JDK7. The
project wiki page is located at
http://wikis.sun.com/display/Javadoc/Home. As a part of the proposed
improvements, the UI of the javadoc output will be revamped. The new
design screenshots are uploaded to the project wiki. The javadoc output
markup will be modified to be valid HTML and WCAG 2.0 compliant.
So there is definitely still work going on there, even if somewhat late. However, in my eyes one of the biggest drawbacks of Javadoc is its very close coupling with HTML. Many classes have Javadoc which includes literal HTML and relies on the output being HTML, too. Unfortunate, but this won't change anytime, I think. Still, this means that developers are free to include whatever they want in HTML there which might as well be invalid, non-well-formed, etc. So adapting the output from the javadoc tool is only one part of this, the other won't and can't change and thus remains.
As for browsing documentation I also find the HTML documentation a little unwieldy. I usually use the Javadoc view in Eclipse. It has drawbacks as well (slow and you can't really search) but it's Good Enough™ for most things.
Personally I still find Javadoc to be very useful. Especially since it is standardized. I don't know of any major documentation style that I find easier to navigate (that might very well be subjective, but I personally find MSDN horrible to use, for example).
For the search: Use the Javadoc Search Frame, it makes using Javadoc of all kinds a lot easier. It's available as a Userscript for Firefox and as a Google Chrome Extension.
To answer your Practical Question, I googled and asked friends and came up with these. Forrestdoc,doclet and doxygen.
The second question, I would say that yes, its not very "Web-oh-twoeye" but At least your guaranteed to work in an offline environment, and its small enough to ship along with your API. i dispise the use of frames, but then it works rather well for javadoc. I have not seen any plans to change it.
Eclipse has some support for javadoc as far as reading, interpreting and generating it goes.
You might want to phrase that in a less agressive and overbearing manner. Most people don't care what a technical resource looks like, and "It's not Web 2.0 enough!" sounds like vapid marketroidspeak.
And what exactly would you consider "more usable"? Personally, I would definitely like a full text search and a better useage browser, and AJAX could probable help with those.
Well, the nice thing about JavaDoc is that it's the opposite of outdated - it's arbitrarily extensible. Why don't you go ahead and write a doclet that produces the kind of API doc you want?
Why nobody else has done that so far (which apparently is the case) is anyone's guess - maybe nobody else feels as strongly about it as you.
There's a DocBook doclet. DocBook is a richer document type than (X)HTML and is better for describing technical content. From DocBook source you can generate all sorts of different output formats.
I personally would like a more readable "comment documentation" standard than the HTML (and hence tag-wieldy) JavaDoc.
For example, MarkDown, as used here, would be excellent, human readable in the source, nicely formatted external to the source.
With the current JavaDoc, I imagine many people use JavaDoc comments, but don't actually document to the extent they could. I'm sure everyone has browsed an API's online JavaDoc that has been non-documented or barely-documented, and thus far harder to use than it should be.
This isn't helped by code-reformatters (e.g., within Eclipse, or maybe upon source commit) that totally destroy any readable structure you might have put within a JavaDoc comment (e.g., a list of items) into one big blob of text, unless you literally use two carriage returns where you wish to use one).
Does anyone know, if there some plans to evolve Javadoc, in a somehow-standardized way?
The corresponding JSR (JSR 260), which specifies enhancements to Javadoc, has been voted out of JDK 7 (for now). An overview of what was planned (from this site):
Upgrade Javadoc to provide a richer set of tags to allow more structured presentation of Javadoc documentation. This JSR covers: categorization of methods and fields, semantical index of classes and packages, distinction of static, factory, deprecated methods from ordinary methods, distinction of property accessors, combining and splitting information into views, embedding of examples and common use-cases, and more.
The overall outlook for JDK 7 is pretty grim.
JavaDoc is itself extremely flexible because you can replace the standard doclet with a custom doclet to provide something that meets your projects specific needs.
On the project I've been working on, we created an HTML/XML-based documentation system (using client-side XSLT 2.0 on JS) for our product with JavaDoc fully integrated. For this, a custom doclet was used to produce JavaDoc data in XML, this used tagsoup to ensure even HTML markup within code comments were well formed.
With this, we were able to deliver an interactive user experience using a single-page app (similar to a desktop tool), but all from within the browser - without any server-side code/infrastructure. The viewer included standard features such as search, tree navigation etc.
Here's a link to a sample entry point in the rather vast documentation:
JavaDoc viewer sample
Here's an image also:
A smart seachable javadoc viewer:
For many times, I face the problem of browsing JavaDoc. I was looking for something just like Adnroid doc search option. At last I get something like that. If you use firefox the solution is here.
Install the plugin GreaseMonkey, its kinda customizing web page the way we see. ( We need to customize any java doc page, so we can search on class name)
https://addons.mozilla.org/en-US/firefox/addon/greasemonkey/
For greasemonkey to work, we need some user script for customization. This can be downloaded by greasemonkey automatically. Install the userscript from JavaDoc search frame or JavaDoc incremental search.
This works great for me.
This question already has answers here:
Where can I find a Java to C# converter? [closed]
(9 answers)
Closed 7 years ago.
Is there an effective tool to convert C# code to Java code?
I have never encountered a C#->Java conversion tool. The syntax would be easy enough, but the frameworks are dramatically different. Even if there were a tool, I would strongly advise against it. I have worked on several "migration" projects, and can't say emphatically enough that while conversion seems like a good choice, conversion projects always always always turn in to money pits. It's not a shortcut, what you end up with is code that is not readable, and doesn't take advantage of the target language. speaking from personal experience, assume that a rewrite is the cheaper option.
We have an application that we need to maintain in both C# and Java. Since we actively maintain this product, a one-time port wasn't an option. We investigated Net2Java and the Mainsoft tools, but neither met our requirements (Net2Java for lack of robustness and Mainsoft for cost and lack of source code conversion). We created our own tool called CS2J that runs as part of our nightly build script and does a very effective port of our C# code to Java. Right now it is precisely good enough to translate our application, but would have a long way to go before being considered a comprehensive tool. We've licensed the technology to a few parties with similar needs and we're toying with the idea of releasing it publicly, but our core business just keeps us too busy these days.
This blog post suggests useful results from Tangible.
There is a tool from Microsoft to convert java to C#. For the opposite direction take a look here and here. If this doesn't work out, it should not take too long to convert the source manually because C# and java are very similar,
These guys seem to have a solution for this, but I haven't tried yet. They also have a demo version of the converter.
Although this is an old-ish question, take a look at xmlVM http://www.xmlvm.org/clr2jvm, I'm not sure if it's mature enough yet, although it has been around for several years now. XMLvm was made, I believe, primarily for translating Android Java apps to the iPhone, however, its XML-code-translation-based framework is flexible enough to do other combinations (see the diagrams on the site).
As for a reason to do this conversion, maybe there is a need to 'hijack' some of the highly abundant oss code out there and use it within his/their own [Java] project.
Cheers
Rich
Try to look at Net2Java It seems to me the best option for automatic (or semi-automatic at least) conversion from C# to Java
They don't convert directly, but it allows for interoperability between .NET and J2EE.
http://www.mainsoft.com/products/index.aspx
C# has a few more features than Java. Take delegates for example: Many very simple C# applications use delegates, while the Java folks figures that the observer pattern was sufficient. So, in order for a tool to convert a C# application which uses delegates it would have to translate the structure from using delegates to an implementation of the observer pattern.
Another problem is the fact that C# methods are not virtual by default while Java methods are. Additionally, Java doesn't have a way to make methods non virtual. This creates another problem: an application in C# could leverage non virtual method behavior through polymorphism in a way the does not translate directly to Java.
If you look around you will probably find that there are lots of tools to convert Java to C# since it is a simpler language (please don't flame me I didn't say worse I said simpler); however, you will find very few if any decent tools that convert C# to Java.
I would recommend changing your approach to converting from Java to C# as it will create fewer headaches in the long run. Db4Objects recently released their internal tool which they use to convert Db4o into C# to the public. It is called Sharpen. If you register with their site you can view this link with instructions on how to use Sharpen:
http://developer.db4o.com/Resources/view.aspx/Reference/Sharpen/How_To_Setup_Sharpen
(I've been registered with them for a while and they're good about not spamming)
I'm not sure what you are trying to do by wishing to convert C# to java, but if it is .net interoperability that you need, you might want to check out Mono
This is off the cuff, but isn't that what Grasshopper was for?
Well the syntax is almost the same but they rely on different frameworks so the only way to convert is by getting someone who knows both languages and convert the code :) the answer to your question is no there is no "effective" tool to convert c# to java
Possibly you could use jni4net - opensource bridge instead ?
Or list of other options I know.
Why not write it in Haxe (http://haxe.org/) and convert it to whatever you want it to be?