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).
Related
I refactored a class by moving some of the methods to different class. Since this was like an Architecture refactoring and not code refactoring, I was wondering if it is a good practice to mention in the javadoc of the new classes that it contains the methods moved from previously existing X class?. For example
/**
Processor that sets sequence to the payment group. This processor has been added as part of checkout refactor project and xxxMethod() method has been moved from {#link XXXFormHandler} to this pipeline processor.
**/
I like this approach since it gives clear picture to any developer involved in maintaining this code. My only concern is if this is exposed as an API, then those information will be shown to everyone.
I don’t think that this is useful. You had strong reasons to refactor the code so developers knowing the new code only should not bother with the old architecture. Developers knowing the old code only don’t know where in the new code they have to look for that javadoc and once they know, they don’t need it anymore. So they need a migration guide which exists independently of the javadoc.
Regarding the last concern, if API users shall not see the particular documentation, regular comments do the right thing as maintainer seeing the source code see the comments.
Weird title, I know, let me explain.
I am a developer most familiar with C# and Javascript. I am completely sunk into those semi-functional worlds to the point that most of my code is about mapping/reducing/filtering collections. In C# that means I use LINQ just about everywhere, in Javascript it's Underscore.js and jQuery.
I have currently been assigned to an ongoing Java project and am feeling rather stifled. I simply do not think in terms of "create an array, shuffle stuff from one to another". I can (and did) create my own versions of the main map/reduce functions using anonymous types implementing interfaces but why re-invent the wheel? The project I am currently on already has commons-collections-3.1.jar and looking through the classes contained it seems like it likely can do everything that I want and more.
For the life of me, I can't find how to actually use it. Looking through the dozens of classes therein is not very helpful and the only thing I can google up is the api doc which is equally as helpful.
How do you use it to Map/Select, Filter/Where, Reduce/Aggregate? Is there anywhere that gives an actual tutorial on this library?
(Comment as answer for formatting purposes.)
Not so much, other than the limited user guide.
That said, I'm not sure where specifically you're having problems--filtering and selecting is mostly wrapped up in the functors package, and utilized by the CollectionUtils class.
While you're not looking for a replacement, you might find things like Guava or Lambda4J a bit more similar to what you're used to (within Java's constraints), and they're a bit less verbose.
Try these links :
http://commons.apache.org/collections/userguide.html (basic tutorial)
http://larvalabs.com/collections/tutorial.html (advanced tutorial with generic)
#george-mauer, you might have to rely on articles like this or a book like Jakarta Commons Cookbook. I have also found it rather useful to learn by creating samples of my own.
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.
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.
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.