Skip to content

Add checks for Documentation Comments Style Guide - Format of a Doc Comment #19821

@gianmarcoschifone

Description

@gianmarcoschifone

Parent issue: #19807

Coverage table

Format of a Doc Comment

Chapter link

Content

Image

Image

Text

A doc comment is written in HTML and must precede a class, field, constructor or method declaration. It is made up of two parts -- a description followed by block tags. In this example, the block tags are @param, @return, and @see.

/**
* Returns an Image object that can then be painted on the screen. 
* The url argument must specify an absolute <a href="#{@link}">{@link URL}</a>. The name
* argument is a specifier that is relative to the url argument. 
* <p>
* This method always returns immediately, whether or not the 
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives 
* that draw the image will incrementally paint on the screen. 
*
* @param  url  an absolute URL giving the base location of the image
* @param  name the location of the image, relative to the url argument
* @return      the image at the specified URL
* @see         Image
*/
public Image getImage(URL url, String name) {
try {
return getImage(new URL(url, name));
} catch (MalformedURLException e) {
return null;
}
}

Guidelines

Status Guideline Check Coverage Notes
🟢 Covered A doc comment must precede a class, field, constructor or method declaration InvalidJavadocPosition
JavadocVariable
MissingJavadocMethod
MissingJavadocType
This is enforced through a combination of checks. InvalidJavadocPosition ensures the comment is correctly placed, while MissingJavadocType, MissingJavadocMethod, and JavadocVariable ensure that classes, methods, constructors, and fields are properly documented.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions