We've got a large codebase of Java (with a smattering of Groovy mixed in) that, by and large, has no javadocs written for it.
However, much of the code is reasonably well documented in "old-school" comments scattered throughout the body.
We're now on something of a push to try and get things documented a little better - Javadocs are now being generated on a regular basis, for example. As a stopgap measure, it would be really nice if javadoc would "scrape" the body of the class (or function, or whatever) and toss all the comments within into a "stub" javadoc.
Is there a way to do that?
Sounds like a bad idea, given that javadocs typically describe purpose and usage of elements, and code body comments are (or should be) about the details of implementation.
But if you must, you clearly need to write your own custom doclet that works in concert with a java source file parser (either 3rd party or your own). For each processed class, you would first run the parser on the source file for that given java class and harvest the internal comments, and then augment the (standard) html produced by the (standard) doclet to add the code comments.
A possible strategy that would help make the resultant javadocs sensible would be to include a given method's internal comments for the javadoc for that method. Just use a 'pre' closure and append the parsed comments of the method at the end of the generic javadoc html.
Related
I have a custom XML format that links to Java resources. For the sake of simplicity let's assume my XML file would look like this:
<root>
<java-class>my.fully.qualified.class.name</java-class>
</root>
Eventually my references will be somewhat more complicated. It will not contain the fully qualified class name directly and I will need some logic to resolve the correct class, but I want to keep the example as simple as possible here.
Now I want it to be possible to Strg+Click on the element's text and want IntelliJ to carry me to the .java file, just like it is possible in Spring-XML files. In the IDEA Plugin Development FAQ there is a link called "How do I add custom references to Java elements in XML files?" which so much sounds like exactly what I need. Unfortunately it links to a discussion where someone is more or less done implementing something like this, having some minor problems. Nevertheless I understood that I probably need to write an implementation of the interface com.intellij.psi.PsiReference. Googling for "PsiReference" and "IntelliJ" or "IDEA" unfortunately did not bring up any tutorials on how to use it, but I found the class XmlValueReference which sounds useful. Yet again googling for "XmlValueReference" did not turn up anything useful on how to use the class. At least the PSI Cookbook tells me that I can find the Java class by using JavaPsiFacade.findClass(). I'd be thankful for any tutorials, hints and the like, that tell the correct usage.
The above linked discussion mentions that I need to call registry.registerReferenceProvider(XmlTag.class, provider) in order to register my provider once I eventually managed to implement it, but of which type is "registry" and where do I get it from?
First of all, here's a nice tutorial that came up a few days ago, which explains the basics of IntelliJ plugin development (you should take a look at the section Reference Contributor).
You will likely have to define your own PsiReferenceContributor, which will be referenced in your plugin.xml like this:
<psi.referenceContributor implementation="com.yourplugin.YourReferenceContributor"/>
In your reference contributor, there's a method registerReferenceProviders(PsiReferenceRegistrar) where you will be able to call registry.registerReferenceProvider(XmlTag.class, provider).
Finally, in your instance of PsiReferenceProvider, you will have to test the tag name to filter out tags which don't contain class references, then find the right Java class using JavaPsiFacade.findClass().
From my experience, the best place to get help regarding IntelliJ plugin development is JetBrains' forums.
I'm new to Doxygen and I'm trying to document an API I am planning to open source. I'd really like to build two sets of documentation, one for end users of the API and one for those who intend to modify it. Is there a way to tag Doxygen comment blocks in a way such that I can generate "user" and "dev" documentation trees? Is there a better solution to my problem? Thanks!
Depending on how your code is structured, you might be able to get away with using two Doxygen config files each including separate source files. The "user" config file would only list the source files containing the public interface to the API, while the "dev" config file would list all source files for the whole project.
This does mean that all your interfaces (e.g. abstract base classes) will need to be documented with the user in mind, but that is usually not a problem as by definition there is unlikely to be any implementation details in an abstract base class.
All your "dev" documentation then sits in the actual classes implementing the interfaces, which are never seen by the API and can be safely omitted by the "user" Doxygen config file.
Of course if your code isn't structured this way it's not going to work, so the only solution I can think of is to fill your comments with a bunch of conditional statements.
In addition to what Malvineous already said, there is the \internal doxygen command.
\internal lets you hide or show part of the documentation by changing INTERNAL_DOCS in the Doxyfile
More information here: http://www.doxygen.nl/manual/commands.html#cmdinternal
I have files named xxx.java.i,xxx.java.d,xxx.jar.i. I know that these file are somehow related to Java. What does this extension mean and for what is it used? Is it same type as the .class extension?
You should look at your build system for more information. It is possible that these are intermediate files that get transformed and renamed to ".java". For example, I've seen various build systems that use the ".i" suffix to mean "input", and perform various forms of variable substitution (e.g. changing something like "{VERSION_NUMBER}" to the version number of the library being compiled).
I think they are created by someone to serve his own purpose and unless we ask the author or see the content we won't know what it the purpose is.
If you see garbled characters, it's probably java bytecode and you can use some decompiler to see the code (see: How do I "decompile" Java class files?).
If you've used javadoc and then come to doxygen, you may know what I mean when I say I miss the hierarchical (frame-based) view that made jumping from class to class and method to method easy. (For those who haven't seen it, imagine a tree-navigator in an IDE or over a filesystem).
How can I get Doxygen to include a navigation tree, if it's even possible?
A similar question was asked in October, but that was just about stylesheet alternatives and only one turned up. I think I'm looking for something more major.
Note that all you need to do to get the tree on the left in Quinn's example is setting GENERATE_TREEVIEW to YES in the config file.
At a basic level, Doxygen output is what it is, and I don't think there's "a better way to view" static HTML content. I think what you want is for Doxygen to produce HTML output that is more similar to Javadoc, which has both pros and cons. (The biggest drawback is that it's unlikely to happen, due to the effort involved and the broad user base.)
I manage a project that is documented using Doxygen, and I'm not sure to what degree my config uses the Doxygen defaults, but I get a sections in the left frame for a flat class list and a class hierarchy. Also, since I have diagrams enabled, the Graphical Class Hierarchy is a fairly quick way to jump to where I want. I haven't delved into Doxygen modules, so I don't have any experience with whether that might segment things similar to how Javadoc does with packages.
What is a tool or technique that can be used to perform spell checks upon a whole source code base and its associated resource files?
The spell check should be source code aware meaning that it would stick to checking string literals in the code and not the code itself. Bonus points if the spell checker understands common resource file formats, for example text files containing name-value pairs (only check the values). Super-bonus points if you can tell it which parts of an XML DTD or Schema should be checked and which should be ignored.
Many IDEs can do this for the file you are currently working with. The difference in what I am looking for is something that can operate upon a whole source code base at once.
Something like a Findbugs or PMD type tool for mis-spellings would be ideal.
As you mentioned, many IDEs have this functionality already, and one such IDE is Eclipse. However, unlike many other IDEs Eclipse is:
A) open source
B) designed to be programmable
For instance, here's an article on using Eclipse's code formatting functionality from the command line:
http://www.peterfriese.de/formatting-your-code-using-the-eclipse-code-formatter/
In theory, you should be able to do something similar with it's spell-checking mechanism. I know this isn't exactly what you're looking for, and if there is a program for doing spell-checking in code then obviously that'd be better, but if not then Eclipse may be the next best thing.
This seems little old but seems to do a good job
Source Code Spell Checker