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
Related
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 need to parse a sequence of Prolog statements and I've been putting together ad-hoc regexs to handle them but the result is not very robust. I noticed java.util.regex.Pattern.Prolog, which is a subclass of java.util.regex.Pattern.Node, but I can't seem to find anything that explains what these classes are for or how to use them. The Javadocs are mostly empty. Are there tutorials or fleshed-out documentation of the purpose and usage of these classes? Can they be used to parse Prolog?
Those classes have package access modifiers. For example, Node, in Oracle JDK 7, is declared as
static class Node extends Object {
They can only be accessed from classes in the same package. However, since that package is typically secured by the JVM, you cannot add your classes to it. You'll get an exception like
Exception in thread "main" java.lang.SecurityException: Prohibited package name: java.util.regex
You can find and copy the source code if you want, but you will not be able to use the classes themselves.
As for their purpose, you have to again go to the source code and look at the comments.
/**
* The following classes are the building components of the object
* tree that represents a compiled regular expression. The object tree
* is made of individual elements that handle constructs in the Pattern.
* Each type of object knows how to match its equivalent construct with
* the match() method.
*/
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.
What I want is to obfuscate my java file but want to keep the class name and method name as it is. Is there any java obfuscator which provides such functionality?
I have tried pro guard gui obfuscator but can't get what I want.
ProGuard can do what you describe. If you don't want it to rename classes and methods:
-keep,allowshrinking,allowoptimization class * { <methods>; }
If you don't want it to rename, remove, or optimize any entry points at all (e.g. merge classes, inline short methods, inline constant fields, remove unused parameters, etc.):
-keep class * { *; }
At that point, there won't be much room left to optimize or obfuscate the method bodies, so you may want to evaluate if this is really what you want.
See Allatori. It allows you to specify which names you don't want renamed.
To expand, you would specify the names you want to keep using a configuration file.
<keep-names>
<class access="private+"/>
<field access="private+"/>
<method access="private+"/>
</keep-names>
The above snippet shows how you can omit name obfuscation. This particular example ignores class, field and method types that have private access or above (i.e. all class, field and method types).
Take a look at Zelix KlassMaster.
See our Java Obfuscator. You can tell it which identifiers must be preserved in the obfuscated program.
The company I work for has long produced a java obfuscator called dashO that can do just this. So add that to the list of evals to try out if you're so inclined :)
I've just started using Java's enums in my own projects (I have to use JDK 1.4 at work) and I am confused as to the best practice of using JavaDoc for an enum.
I have found that this method works, but the resultant code is a little unrefined:
/**
* Doc for enum
*/
public enum Something {
/**
* First thing
*/
FIRST_THING,
/**
* Second thing
*/
SECOND_THING;
//could continue with more
}
Is there any way I could break up the enum declarations on their own lines without chaining them by commas, or is this the best approach for using JavaDoc for an enum?
To answer the first part of your question, you do have to separate each enum value with a comma. As far as I know, there's no way around that.
Personally I don't have a problem with the code the way you've presented it. Seems like a perfectly reasonable way to document an enum to me.
As Mike mentioned, you do have to separate the enum values with commas, and they have to be the first things listed in the enum declaration (instance variables, constants, constructors and methods may follow).
I think the best way to document enums is similar to regular classes: the enum type gets a description of the function and role of the enum as a whole ("Something values are used to indicate which mode of operation a client wishes...") and each enum value gets a Javadoc description of its purpose and function ("FIRST_THING indicates that the operation should evaluate the first argument first..").
If the enum value descriptions are short you might want to put them on one line as /** Evaluate first argument first. */, but I recommend keeping each enum value on its own line. Most IDEs can be configured to format them this way automatically.
There is a google code search online tool -- http://www.google.com/codesearch
I try to lookup stuff by doing something like "lang:java public enum"
An example from Sun