What changes to javadoc should be made when renaming a class? - java

Say I have a class, and I renamed it.
How should i change the documentation of the class?
This is what the the javadoc of the class currently looks like
/**
* Single report.
*
* <p>There is no thread-safety guarantee.
*
* #author Yegor Bugayenko (yegor256#gmail.com)
* #version $Id: 532ae3783f6bcb7ffa6819b91ebee78670aa82e3 $
* #since 0.1
* #checkstyle ClassDataAbstractionCouplingCheck (500 lines)
* #checkstyle JavadocTagsCheck (500 lines)
*/

If the change only affects the name of the class, only the name occurrences in documentation, configuration and other references need to be replaced accordingly. As the JavaDoc does not contain any class names, there's nothing to do in that particular place.
IDE's like IntelliJ or Eclipse can help a lot when doing refactorings like that because they offer tools to perform the replace in a safe and convenient way. In simple cases a text editor with search and replace functionality might suffice.
After an automatic replace I'd go through all the changes manually and double check if they had the intended affect as sometimes the context is affected from the change as well and needs to be adapted.

Related

Is there any difference between these multi-line comments in Java?

I just wanted to know if there are any differences between these types of comments.
/*
...
Content of the comment
...
*/
and
/*
* ...
* Content of the comment
* ...
*/
No, there is no difference. It's purely a style decision.
No difference, but this syntax
/*
* ...
* Content of the comment
* ...
*/
is more appropriate for generating JavaDoc
From http://javadude.com/articles/comments.html
Documentation comments should (at very least) be used in front of
every public class, interface, method and class/instance variable in
your source code. This allows someone to run javadoc against the code
and generate a simple document that lists the public entities and a
brief description of each. You may also use documentation comments in
front on non-public methods, and use a javadoc option to generate
documentation for them. Using documentation comments on non-public
entities is not as important as publics (the interface isn't
exposed...) but if you're commenting the code anyway you might as well
write those comments as documentation comments.
No it makes no difference.
Side Note (for the sake of completeness)
There is a difference between the following to examples.
/*
* ...
* Content of the comment
* ...
*/
and
/**
* ...
* Content of the comment
* ...
*/
the second one indicates a javadoc comment (the ** at the first line of the comment). There you can use different tags to enhance your javadoc.
There isn't any difference. Just a different way.
I'd prefer the first form:
/*
something
*/
Specially if the commented out part is code and if I am trying something out. For obvious reasons, extra asterixes at the beginning of each line causes head aches for this case.
Modern IDE's also support short-cuts for commenting multiple lines at the same time. For example in Eclipse, you can select a few lines and press CTRL + / to comment them out. The form of comments is though would be as follows:
// line1
// line2
// ...
There is no difference
As a developer What ever the code we are writing we need to make a small document on top of that particular code.for documenting purpose we will use these comments based on our choice we can use what ever we want.

Java: Purpose of annotations in comments?

What is the purpose of (what look like) annotations placed in comments? For example, I'm seeing the following comment above a method in an interface:
/**
* Create saved search
* REST: POST /lifecycles/savedsearches
* #param controlParameters control parameters
* #param search savedSearch object
* #throws ProcessingException if any processing exceptions
* #return Updated Object
*/
I understand the meaning of the comment, just wondering why this syntax was used.
These annotations are important for the javadoc tool. When it generates a documentation for a class/interface/enum/constructor/method if parses the content between /** and */.
For a single piece of javadoc content, the tool generates a HTML-based documentation, which consists of several paragraphs. When it detects an annotation (e.g. #param) it adds the corresponding #param information to the paragraph about the Parameters of a method.
Checkout the String#concat(String str) method, for example.
Also, take a look on the Oracle's Javadoc home page
This is used when generating Javadoc. That way you can add an explanatory text for each parameter passed to the function and you can explain what's returned and what exceptions can be thrown and the Javadoc generator then adds your comments to the methods documentation in its corresponding places.
Then you can use that to generate html pages documenting your code based on these comments.
It's used then for javadoc generation. See http://www.oracle.com/technetwork/articles/java/index-jsp-135444.html
This syntax is used if you generate Javadoc.
http://www.oracle.com/technetwork/articles/java/index-137868.html

Custom Java Code Library Usage Tips

I am developing a library which is used for some specific validation operations. Every thing is ok for me in usage, but when I publish it, every time developers need to read manual document.
So, I want to show usage tips like shown blow.
How can i do it ?
You need to write JavaDoc comments in your code and then you can generate JavaDoc html.
JavaDoc comments are special comments which are between /** and */ and can be used to generate JavaDoc. e.g.
/**
* Class description.
* <p>
* Some more details
*
* #author Edd
*/
public class MyClass {
/**
* Method description.
*
* #param param
* important parameter
*/
public static void myMethod(String param) {
}
}
This would then look like this as a tooltip:
When you release your library for other developers to use, you would typically release it as a jar file. When you package up your jar you should also generate a javadoc.jar file to accompany your jar. This can then be used by other developers to get the usage tips.
Write JavaDoc comments and publish them together with your library.
If you are using Maven, you can use the javadoc:jar goal of the Maven Javadoc Plugin.
Read about and use javadoc, here: http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html

Inline comments in Java: /** opposed to /*?

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.

How do I modify the Javadoc when I modify someone else's code?

I am working on someone else's code and making significant modifications. (I am converting it to use a different database than the one he originally used.) How do I indicate in the Javadoc comments that I am not the original author of the code, but that I did make contributions to it. Is there a clean or standard way of doing this already? My Googling is not helping me figure this out.
Example:
/**
* This class does some really awesome stuff.
*
* #author Steph the Great - Modified to use PostgreSQL instead of Derby;
* added comments to the code
*/
I also don't know the original author's name, so all I can put down is myself . . .
Those comments do not belong in the javadoc :-) The javadoc should explain the contract -- it is what is extracted and displayed in the auto-generated "documentation". The rest are just normal comments or, perhaps better yet in this case, SCM log entries and have no place in the javadoc!
I would likely just leave the original author, but if you want credit...
...see the #author javadoc reference and note that it can be included multiple times. This section explicitly relates to multiple authors and ordering, etc.
/**
* This class does some really awesome stuff.
* It uses PostreSQL.
*
* #author Steph the Great
* #author Freddy Four Fingers
*/
// DEC2012 - Fred - Modified to use PostgreSQL instead of Derby (but really, use SCM!)
class Awesome { ... }
Happy coding.
Notes on question somewhat unrelated to example in post... if the author isn't known, then several things can be done. First and foremost add a link or reference to where the original source was obtained -- an optional "I didn't write this originally" for clarity can be noted as well.
Then, depending upon your preference:
Don't specify an #author field -- not even yourself. It's not required.
Add yourself as the sole author; the original source is mentioned above in the javadoc
Add a dummy author and yourself as the second author, e.g. #author Unknown #author unascribed (see comments and #author).
Do whatever you want within terms of the license, if any.
You can have more than one #author tag. So, if you've made extensive changes to a class, just add a new #author tag with your own name in it. There's no need to list the changes you've done---the revision history should show that well enough.

Categories