When programming in C++, I use Doxygen and frequently create external .dox files for additional documentation that won't fit well in a specific class or method - for instance, file format documentation (for files that are accessed by multiple classes). I tried to find a way to do the same in Java, but it appears that javadoc doesn't have an equivalent feature, all documentation must be written inside the comments of a .java file and is tied to it (or at least to its package). Am I right? Is there an alternative way to do this?
The section “Miscellaneous Unprocessed Files” from the javadoc documentation is what you’re looking for.
If you're asking if Javadoc can create external documentation, then the answer is no. But you can link to external documentation you've already made. Additionally, if something applies to the package level, you can put the documentation in the package file instead of attaching it to a particular class or method.
Related
In order to create a valid .class file, every method has to have a full internal name and type descriptors associated with it. When procedurally creating these, is there some sort of lookup table one can use (outside of Java, where a ClassLoader can be used) to get these type descriptors from a method name? For example, how would one go from Scanner.hasNextByte to boolean java.util.Scanner.hasNextByte(int) / boolean java.util.Scanner.hasNextByte() (or even from java.util.Scanner.hasNextByte to boolean java.util.Scanner.hasNextByte(int) / boolean java.util.Scanner.hasNextByte())? The above example has overloading in it, which is another problem a human- but mostly computer-readable declarations file would hopefully address.
I've found many sources of human-readable documentation like https://docs.oracle.com/javase/8/docs/api/index.html containing uses of each method, hyperlinks to other places, etc. but never a simple text file or collection of files containing just declarations in any format. If there's no such file(s) don't worry about it, I can try and scrape some annoying HTML files, but if there is it would save a lot of time. Thanks!
The short answer is No.
There isn't a "header file" containing the class and method signatures for the Java class libraries. The Java tool chain has no need for such a thing. Nor do 3rd-party Java compilers, or compilers for other languages that rely on the Java SE class libraries.
AFAIK, there isn't a 3rd-party tool that builds such a file or an equivalent database or in-memory data structures.
You could create one though.
You could chose an existing Java parsing library, and use it to build parse trees for all of the source files in the class library, and emit the information that you need.
You could potentially create a custom Javadoc "doclet" plugin to emit the information.
Having said that, I don't understand why you would need such a mapping. Surely, your IDE does this already ... and exposes the information via some internal API. And if this is not for an IDE plugin, what it is for?
You commented:
I'm making a compiler for a JVM-based programming language ....
Ah ... so your compiler should do what other compilers do. Get the information from the ".class" file. You can either load the class using a standard or custom class loader, or you can use a library like asm or bcel or javassist ... which can read a ".class" file without loading it.
(I haven't checked, but I think the standard javac compiler uses an internal API to do this.)
Note that your proposed approaches won't work for interfacing with 3rd-party Java libraries where the source code is not available and/or the javadoc is not scrapable.
What about building it from the source files for the standard library?
The Oracle Java 8 API web pages you referenced was created by Javadoc processing of source files for the Java standard library.
If you use an IDE with a debugger, there is a good chance you already have much of the standard library source code downloaded. After all, if you set a break point, and then follow the program step-by-step with "Step into", you can trace the execution of the program into standard library methods. The source files would be part of the JDK.
However, some parts of the standard library source might not be available, due to licensing restrictions.
For Java source files, I would like to find out:
Which classes use which other classes (fully qualified names)?
Which methods call which other methods (fully qualified names)?
What would be a reasonable way to achieve that?
EDIT:
To clarify: I want a list of source code files as input. The output should be (as specified above) which class uses which other class and which method calls which other method. I do not want to inspect other loaded classes at runtime, like when using reflection.
You need to use static analysis tool as STAN standalone mode:
The standalone application is targeted to architects and project managers who are typically not using the IDE.
Or JArchitect (available also using command line)
JArchitect is a powerful tool for static code analysis. It can provide a lot of insight into complex code bases. Using custom code queries you are able to build your own rule sets in a very comfortable way.
In the Class Browser right-click menu, JArchitect proposes to explore the graph of dependencies between members (methods + fields) of a type.
Another option is SourceTrail
The graph visualization provides a quick overview of any class, method, field, etc., of interest and all its relations. The graph is fully interactive. Use it to move through the codebase by focusing on related nodes and edges.
(source: sourcetrail.com)
Unfortunately, reflection doesn't give you all the information you need to do this.
I've done it with ASM (https://asm.ow2.io/).
It provides the ability to walk the byte code of all of your classes using the visitor pattern, including the actual method implementations, from which you can extract the references to other classes.
I'm sorry that I cannot provide the implementation, because it's proprietary.
Note that this works from your .jar files, not your sources. If you really need to work from sources, then have a look at https://github.com/javaparser . Really, though, it's better to use the byte code, since the java language changes frequently, while the byte code specification does not.
I am not sure how to get a listing, but for identifying refactoring opportunities, you might try IntelliJ IDEA. It will dull out the signature line of any methods that are not accessed in the project. It will also detect code segments that are repeated elsewhere in the project, so you can extract common code.
I have this model object representing a Java source file.
It has a constructor like so:
private SourceFile(File file)
I want this constructor to actually make sure (as much as it can) that the File it's being given is actually a Java source.
I have a batch operation that takes a lot of text files. Some of them are Java sources, I wan't a good way to differentiate them (other than file extension).
So has anyone been in this situation before and can you recommend a good way to check plausibility (not validity, for a validity check I'd need to compile it) ?
I'd do two things:
Check that the file ends in .java.
Check that the file declares a class that has the same name as the file (see here).
It depends on how accurate you want to be. If you want 100% you have to compile it. If you would be happy with something low you can check printable characters. Reasonable level may be achieved by key work check. And so on...
Use javaparser, on given link is wiki how to use it. But in Java 1.6 the compiler has an API build in the JDK, through it you can access the results of the Java parser.
I'm working on a simple parser to transform java-interfaces and value objects to C#. This is done, so a C# client to communicate with the java JMS server can be created automatically.
My parser is almost finished, I can read generic-informatins, reuse C# types, and even merger getter and setter methods to properties. The only thing i can't, because it's not possible to be done with reflections, is to read the parameter names of methods in an interfaces. I found a library (BCEL) and can read the parameter names of "real" methods, in classes, but not within an interfaces.
So my idea was, eitherway it would be cool to have the former java comments also transfered into .net, so i could use it and i could use the very same tool to get the parameter names, since they can also read them.
So my question, do you know of any library which i could use for this? I have the generated javadocs and also the sourcecode which i could use as a source for the tool.
Thank you very much
cheers
zahorak
If you have access to the source code, the easiest way would be to use a custom Javadoc doclet. This gets access to all the declarations (including parameter names), and also all comments. You can then convert it in any format you want.
If you only have the Javadoc output, I suppose most IDEs have some way of parsing it. Have a look at Eclipse or Netbeans, maybe their Javadoc parsing code is extractable.
I have what must surely be a fairly common documentation need...
I'm implementing a rather sizable Java library code base that has, among other things, various classes intended to be exposed to a caller/implementor at the appropriate level of abstraction. At the same time, the code base contains, of course, various internal classes, interfaces, and other abstractions that the user of the library doesn't need to know about in order to use the API.
Lots of other API libraries out there make the mistake of simply throwing everything into the Javadocs, and leaving it up to the user to figure out which objects and entities they actually need to deal with as a caller through some combination of guesswork, inference, and, if you're lucky, example code.
I don't want to be in that same position. I would like to have an "internal" set of Javadocs that expose the entire extent of the codebase, and an "external" set of Javadocs intended to clearly communicate to the developers the characteristics of the classes that they actually need to use to get their work done. I don't need or want to muddy the waters with various internal abstractions that they don't need to see or know about - there's no need for them to know how it all works under the hood, and it would just confuse and misdirect them, making for a very inefficient API learning process.
How can I accomplish this? Is there a well-known combination of arguments to 'javadoc' and perhaps some annotations that can make this happen?
Thanks very much for your consideration!
Assuming that you have followed best-practice and put your internal classes in different packages to your public APIs, you can run javadoc with the public API package names as command line arguments.
Refer to the javadoc command line synopsis for more details.
(If you haven't organized your packages to keep internal classes out of API packages, you may be in for a bit of pain ...)
In addition to Stephen C's answer and using the javadoc tool, you can specify exactly which packages appear in the javadoc (hence Stephen C's comment about 'pain' if they aren't organised logically) using something like this:
Say you have 5 classes and you want only the classes in the org.notprivate package to appear in the Javadoc:
org.notprivate.Foo
org.notprivate.Bar
org.notprivate.Stuff
org.notpublic.Things
org.notpublic.More
You can use something like:
javadoc -d target/api -source 1.6 -sourcepath src/main/java org.notprivate
That's just a quick example, if you need to specify each class you'll need to look at the link Stephen C provided in more detail
Posted here for clarity:
Javadoc Documentation
I would like to have ... an "external" set of Javadocs intended to clearly communicate to the developers the characteristics of the classes that they actually need to use to get their work done. I don't need or want to muddy the waters with various internal abstractions that they don't need to see or know about - there's no need for them to know how it all works under the hood, and it would just confuse and misdirect them, making for a very inefficient API learning process.
Given this desire, perhaps Javadoc isn't the best method of documenting the overall system view or for giving a "here's what you need to know"-type info to new developers?
I would recommend supplementing your Javadoc files with a separate guide/document/wiki/something to give the meta-view.
You can use some extra arguments when invoking the javadoc tool :
-public : Shows only public classes and members.
-protected : Shows only protected and public classes and members. This is the default.
-package : Shows only package, protected, and public classes and members.
-private : Shows all classes and members.
So, with these options you can generate a full documentation for internal usage, and give a 'light' documentation with only the public interface to your customers.
If you're using Eclipse, the Javadoc wizard shows radio buttons to help you choose the documentation level - which is "public fields only" by default.