Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Breaking a long URL to several line in javadoc

If I'm using a piece of code or resources fetch from etc internet I like to point this out in class or function documentation and also provide a link to the original source. However, I would also like to stick to max 80 chars per line principle when writing code for better readability. Is there a way to parse a long URL in source to multiple lines and still maintain the original address as usable when using the javadoc in IDE like Eclipse? And with usable I mean that clicking the URL in javadoc tooltip opens the correct page.

For example, how would you format the following:

/**
 * Class to do some cool stuff
 * Original source: 
 * http://stackoverflow.com/questions/and-huge-amouts-of-URL-address-which-does-not-fit-to-80-chars
 */
public class ExampleClass {

}
like image 656
pnkkr Avatar asked Dec 09 '16 08:12

pnkkr


People also ask

What does @SEE mean in Javadoc?

In short, we use the @see tag when we want a link or a text entry that points to a reference. This tag adds a “See Also” heading to the reference. A document comment can hold any number of @see tags, all of which can be grouped under the same heading.

How do I give a Javadoc a link?

Creating a Link to Javadoc of Another Class To summarize, @link is preferred when we use a class or method name in the description. On the other hand, @see is used when a relevant reference is not mentioned in the description or as a replacement for multiple links to the same reference.

How do you write a good Javadoc?

The correct approach is an @param tag with the parameter name of <T> where T is the type parameter name. There should be one blank line between the Javadoc text and the first @param or @return. This aids readability in source code. The @param and @return should be treated as phrases rather than complete sentences.


2 Answers

If you don't want to use a URL shortener you can surround your url with <pre></pre> tags as follows:

/**
 * Class to do some cool stuff
 * Original source: 
 * <pre>
 * See <a href="http://stackoverflow.com/questions/
   and-huge-amouts-of-URL-address-which-does-not-fit-to-80-chars">NameOfyourLink</a>
 * </pre>
 */

This will satisfy checkstyle for example and let you keep your original URL.

like image 87
Stuart Avatar answered Oct 06 '22 04:10

Stuart


Another solution I found is to just break the lines and make sure the successive ones follow exactly the URL (not have any other character in between).

For example:

/**
* Link to <a href="https://developer.android.com/reference/android/app/Service#
startForeground(int,%20android.app.Notification)">startForeground(..)</a>
*/
like image 40
Mugurel Avatar answered Oct 06 '22 04:10

Mugurel