According to the link, i wrote the following code:
/**
* #hide
* */
public void myMethod() {
// do something
}
When i use the command to generate the doc:
$ javadoc -locale en_US -encoding UTF-8 -charset UTF-8 -d doc xxx.java
The doc still have the myMethod item. So how to hide the myMethod? What did i miss ?
You are using a Doclava tag, but are generating the API documentation using the standard doclet.
Building Doclava
The Doclava source comes bundled with an ant script to build the doclet. The "jar" task will build a jar containing Doclava and all necessary dependencies.
Using Doclava with Javadoc
The command line arguments to pass to Javadoc to use Doclava are: -doclet com.google.doclava.Doclava -docletpath ${jar.file}
As per the official Javadoc FAQ, hiding public members is currently not possible in a direct way.
Occasionally you might need to make a class or method public so that it can be accessible from other packages, not because you want it to be part of the public API. Having these methods appear in the documentation merely confuses application developers.
There is currently no Javadoc option to hide, exclude or suppress public members from the javadoc-generated documentation.
Several options are available:
Excluding source files - You can pass into javadoc only the source filenames for all classes you want to document, and exclude those you want to omit. Notice this has the granularity of files, not classes. Therefore, if you exclude a source file that contains nested classes, they would also be excluded. (You can put the list of classes in a command line argument file rather than directly on the command line.) The default Javadoc offers no way to omit classes when passing in package names on the command line.
Excluding individual classes - You can use the Exclude Doclet. This has finer granularity (class rather than source file) than the previous option, and would be more natural to use because you explicitly list in a file the files you want to exclude.
Excluding classes, methods and fields - The yDoc Doclet has this capability, where you mark items with an exclusion tag in the source code. In addition, anyone is welcome to extend the Exclude Doclet above for methods and fields -- we'd be happy to publish it and add your name to the credits.
We are considering #exclude as a proposed tag for excluding members.
Also check out the Proposed Javadoc Tags page for more info into #exclude and #hide.
Use #hidden tag as below, it was introduced in JDK 9 and works with JDK 17 as well.
class Test {
/**
* This is hidden
* #hidden
*
* #param a
* #param b
*/
public int add(int a, int b) {
return a + b;
}
}
This tag can hide java documentation for APIs, Variables, Constructors etc.
Command to generate javadocs:
javadoc Test.java
Related
I'm aware of the %javamethodmodifiers kludge to get Javadoc comments into generated Java code. For the most part, it works, but I am having no success getting it to work for getter/setter methods generated for a C struct. I've tried placing the %javamethodmodifiers before the struct definition, after it, etc. to no avail.
Is it possible to use %javamethodmodifiers to generate Javadoc comments for the class generated from a C struct?
you can try:
%typemap(javaclassmodifiers) class::enumname "/**
* javadoc
*/
public enum";
this one i know is working for enums, but it may work for all objects that generate java side classes
also you can try standard rename:
%rename("/**
* javadoc
*/
ENUM_CONST") class::ENUM_CONST;
this one is working for enum constants
I am writing a library in Java. I've divided its implementation into Java packages to help manage the complexity. Only one package contains classes that are visible to clients of the library. However, because only public methods are visible outside of the package for use by other packages of the library, I find myself forced to do one of the following:
(1) Only put interfaces and factory methods in the externally-visible package, putting implementations of those interfaces in a separate package, as described in this SO answer. For example external.MyInterface and internal.MyInterfaceImpl. I find this messy.
(2) Make both internal and external methods public in the external package, and attach Javadoc tags to the internal methods so I can remove their docs prior to publication, either manually (error-prone) or by writing some sort of Javadoc preprocessor or postprocessor.
(3) Use a mechanism that Javadoc provides for this purpose -- ideally, a Javadoc tag.
Whatever the approach, all I really care about is having a consistent way to automatically generate Javadocs for just the external APIs. Is there a standard way to do this? A tool for the purpose?
An alternative solution I've been using for years is to add an #exclude tag, using the public domain code provided in this blog: Implementing #exclude using Dynamic Proxies.
To exclude a Java element (attribute, method, constructor, class, inner class or package) from the Javadoc output, just add the #exclude tag in its Javadoc:
public class MyClass {
/**
* This is my internal attribute, javadoc not exposed.
* #exclude
*/
protected String myInternalAttribute;
/**
* This is my external attribute, javadoc is exposed.
*/
protected String myExternalAttribute;
/**
* This is my internal method, javadoc not exposed.
* #exclude
*/
public void myInternalMethod() { }
/**
* This is my external method, javadoc is exposed.
*/
public void myExternalMethod() { }
}
I found these two answers elsewhere on SO. One approach is to create a custom Javadoc annotation and have an Ant task replace the annotation with deprecated prior to generating the Javadoc. The other, far simpler approach is to use Doxygen's conditional inclusion.
I'm not stuck with Javadoc, so I could go with Doxygen. However, looking at Doxygen right now, it's so different from Javadoc that I'm not sure it's worth the learning curve or establishing a precedent just to be able to generate external APIs.
Here's another solution I will try next time I'm in a position to build: I'll demarcate the portions of the source files that are internal-only, write a tool that duplicates the source files of the external package while removing the portions of the files that are demarcated internal-only, and then run Javadoc off of the generated source. This should work unless Javadoc needs the linker to be happy.
I don't know if it's worth keeping my question around. Might help others find the answer, should they be thinking about it the way I was. Even so, no one has presented a great solution yet.
i'm working with Eclipse in Java and with long long classes i need a feature like this: in the top comment of a method (for example) there is a list of operations executed by the method.
For each operation listed, i'd like to "hyperlink" a portion of the comment to a specific line of the related code.
Then using Ctrl+Click to that line i can jump directly to the specified line code.
Is it possible an operation like this?
Thanks
In the comment below your question you say:
how can i link methods?
Take a look at the following example: you can press ctrl + click on bar() within the JavaDoc of foo() and eclipse jumps to the method bar().
public class Example {
/**
* JavaDoc of foo(). This method executes {#link Example#bar()}
*/
public void foo() {
bar();
}
/**
* Javadoc of bar().
*/
public void bar() { }
}
Eclipse even offers autocomplete for #link, the classname and the method (after you manually entered the #).
Is that what you are looking for?
You can use the JavaDoc #see tag:
/**
* #see MyClass#myMethod()
*/
This generates a hyperlink in your JavaDoc.
SRC: method-linking-anchoring-in-java
The Eclipse IDE allows you to go from a method call to the method's definition ('F3' I think).
Apart from that, I don't think there's a way to set up "special" navigation. Mind you, if you need something like that, it is a strong indication that your methods are WAY too large. Refactor them.
Thinking outside of the box, if you were to feed your code through a code-to-html pretty printer, you could embed HTML hyperlinks and anchors in comments (javadoc or normal). With a bit of luck, they would be clickable when you viewed the HTML-ized source code in a web browser.
Of course, Eclipse can follow javadoc "links". Obviously the standard tags can't link to deep inside a method, but I guess you could write an Eclipse plugin that supported non-standard javadoc tags for linking to embedded anchors, and the navigation thereof.
is there a reason i should prefer to write inline-comments in java like this:
/** Init operation */
mindControlLaser.engage();
as opposed to use just one *:
/* i'm a happy comment */
Eclipse colours the syntax differently, but is there really anything in the "toolchain" (javadoc, eclipse, etc.) giving me an advantage when using /** */ ?
No reason for inline comments.
/** signals to javadoc utility to extract documentation about your API automatically. It does not have any effect when is used inside methods.
Regular comments
/* Regular comment */
With regular comments you explain maybe a part of an algorithm that is tricky.
Or anything that you don't want to be a part of the JavaDOC. Inline comments are regular comments too, and can be used for example when the description is shorter.
Java Documentation
/** JAVA DOC COMMENT */
With javadoc you explain classes, methods, or fields(variables).
Then, most IDEs like Eclipse can use this information to help you while you code.
For example, if you have a classA and a classB, and in classB you use stuff from classA, then if you hover on methods or variables you can see the JavaDOC information. It's very handy.
Also, with build tools like ant you can automatically build HTML files out of the JavaDOC, and if you publish them you can allow others to reuse your work.
Look for example the documentation of Java itself here.
The syntax for a comment is /* */.
Javadoc has as a default that you use /** */. This is a comment because the second * is inside the comment, so would not be seen differently by your compiler.
So without a second * you are just adding a comment, and with the second one you write javadoc: eclipse will recognize it and give you hints etc when hovering on the functioncall somewhere else.
/** .... */ will generate Javadoc, /* ... */ won't.
Of course, it will generate Javadoc only when in the correct places. Javadoc also has a pretty well defined format, see here.
The /** denotes "documentation" comments; Javadocs etc. look for these when creating documentation for your code.
So they should really only be used above methods and classes, e.g.:
/**
* Class to represent tigers.
*/
class Tiger {
/**
* Go extinct.
*/
void goExtinct() {
}
}
The /* variant just denotes a standard comment block.
Yep, it's the javadoc notation to use /** Primary sentence. Other descriptions... */. First sentece up to the . will be used in summaries of javadoc and the rest in the detailed view.
Javadoc treats /** differently; classes and methods which have /** comments above them will get put into javadoc output.
If you use the reference formatting (e.g. {#link ClassA}) and rename the class ClassA with Eclipse, it will automatically update the comment if it is a javadoc comment.
I have a deprecated method in my class:
#Deprecated
public void deprecatedMethod() {
//do bad things
}
I don't want that method to appear in the javadoc.
I know there's an option called -nodeprecated which:
"Prevents the generation of any
deprecated API at all in the
documentation."
So I'm using this option and it doesn't exclude the method from javadoc. Is it a bug in javadoc or am I using it wrong? What else can I do?
(I'm using eclipse 3.4.2 to produce javadoc)
You have to include "-nodeprecated" option in the Export to javadoc wizard.
Warning: it is a javadoc option, not a VM option.
I've tested it in Eclipse 3.4 and it worked.
Edit: If you only include Deprecated annotation it doesn't work. You have to include #deprecated tag inside method javadoc as well.
I don't know if there's a way to tell javadoc to use #Deprecated anotation (which curiously doesn't have a message parameter to document why is deprecated and what else to use).
Edit: before-1.5 way of deprecate methods
You have to include a #deprecated tag (or indicator or whatever) with the message you want to display to the user in the javadoc after the "deprecated".
/**
This method sets the property A.
#see getA
#author helios
#deprecated This method is not sync safe, use setAOk instead
*/
public void setA(String value) ...
#helios
john is saying that you must include the #deprecated javadoc tag within the javadoc comment block (/** ... */) as he has done above with:
#deprecated This method is not sync safe, use setAOk instead
Add this, then use the -nodeprecated option when running javadoc and the methods will not appear in the generated doc.