pmd / pmd / 380

Committed 29 Jan 2026 03:55PM UTC coverage: 78.964%. Remained the same

Build # 380

Build Type

push

github

Committed by

adangel

Commit Message

[doc] ADR 3: Clarify javadoc tags (#6392)

Run Details

18537 of 24358 branches covered (76.1%)

Branch coverage included in aggregate %.

40391 of 50268 relevant lines covered (80.35%)

0.81 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

92.5

/pmd-apex/src/main/java/net/sourceforge/pmd/lang/apex/ast/ApexCommentBuilder.java

/*
 * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
 */

package net.sourceforge.pmd.lang.apex.ast;

import static java.util.stream.Collectors.toList;

import java.util.AbstractList;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.List;
import java.util.RandomAccess;

import org.antlr.v4.runtime.BaseErrorListener;
import org.antlr.v4.runtime.CharStreams;
import org.antlr.v4.runtime.RecognitionException;
import org.antlr.v4.runtime.Recognizer;
import org.antlr.v4.runtime.Token;

import net.sourceforge.pmd.lang.ast.LexException;
import net.sourceforge.pmd.lang.ast.impl.SuppressionCommentImpl;
import net.sourceforge.pmd.lang.document.FileLocation;
import net.sourceforge.pmd.lang.document.TextDocument;
import net.sourceforge.pmd.lang.document.TextRegion;
import net.sourceforge.pmd.reporting.ViolationSuppressor.SuppressionCommentWrapper;

import io.github.apexdevtools.apexparser.ApexLexer;
import io.github.apexdevtools.apexparser.CaseInsensitiveInputStream;

final class ApexCommentBuilder {
    private final TextDocument sourceCode;
    private final CommentInformation commentInfo;

    ApexCommentBuilder(TextDocument sourceCode, String suppressMarker) {
        this.sourceCode = sourceCode;
        this.commentInfo = extractInformationFromComments(sourceCode, suppressMarker);
    }

    public boolean containsComments(ASTCommentContainer commentContainer) {
        if (!commentContainer.hasRealLoc()) {
            // Synthetic nodes don't have a location and can't have comments
            return false;
        }

        TextRegion nodeRegion = commentContainer.getTextRegion();

        // find the first comment after the start of the container node
        int index = Collections.binarySearch(commentInfo.allCommentsByStartIndex, nodeRegion.getStartOffset());

        // no exact hit found - this is expected: there is no comment token starting at
        // the very same index as the node
        assert index < 0 : "comment token is at the same position as non-comment token";
        // extract "insertion point"
        index = ~index;

        // now check whether the next comment after the node is still inside the node
        if (index >= 0 && index < commentInfo.allCommentsByStartIndex.size()) {
            int commentStartIndex = commentInfo.allCommentsByStartIndex.get(index);
            return nodeRegion.getStartOffset() < commentStartIndex
                    && nodeRegion.getEndOffset() >= commentStartIndex;
        }
        return false;
    }

    public void addFormalComments() {
        for (ApexDocToken docToken : commentInfo.docTokens) {
            AbstractApexNode parent = docToken.nearestNode;
            if (parent != null) {
                ASTFormalComment comment = new ASTFormalComment(docToken.token);
                comment.calculateTextRegion(sourceCode);
                parent.insertChild(comment, 0);
            }
        }
    }

    /**
     * Only remembers the node, to which the comment could belong.
     * Since the visiting order of the nodes does not match the source order,
     * the nodes appearing later in the source might be visiting first.
     * The correct node will then be visited afterwards, and since the distance
     * to the comment is smaller, it overrides the remembered node.
     *
     * @param node the potential parent node, to which the comment could belong
     */
    public void buildFormalComment(AbstractApexNode node) {
        if (!node.hasRealLoc()) {
            // Synthetic nodes such as "invoke" ASTMethod for trigger bodies don't have a location in the
            // source code, since they are generated by the parser/compiler (see ApexTreeBuilder)
            return;
        }
        // find the token, that appears as close as possible before the node
        TextRegion nodeRegion = node.getTextRegion();
        for (ApexDocToken docToken : commentInfo.docTokens) {
            if (docToken.token.getStartIndex() > nodeRegion.getStartOffset()) {
                // this and all remaining tokens are after the node
                // so no need to check the remaining tokens.
                break;
            }

            if (docToken.nearestNode == null
                || nodeRegion.compareTo(docToken.nearestNode.getTextRegion()) < 0) {

                docToken.nearestNode = node;
            }
        }
    }

    private static CommentInformation extractInformationFromComments(TextDocument sourceCode, String suppressMarker) {
        String source = sourceCode.getText().toString();
        ApexLexer lexer = new ApexLexer(new CaseInsensitiveInputStream(CharStreams.fromString(source)));
        lexer.removeErrorListeners();
        lexer.addErrorListener(new BaseErrorListener() {
            @Override
            public void syntaxError(Recognizer<?, ?> recognizer, Object offendingSymbol, int line, int charPositionInLine, String msg, RecognitionException e) {
                throw new LexException(line, charPositionInLine, sourceCode.getFileId(), msg, e);
            }
        });

        List<Token> allCommentTokens = new ArrayList<>();
        List<SuppressionCommentWrapper> suppressionComments = new ArrayList<>();
        int lastStartIndex = -1;
        Token token = lexer.nextToken();

        boolean checkForCommentSuppression = suppressMarker != null;

        while (token.getType() != Token.EOF) {
            // Keep track of all comment tokens
            if (token.getChannel() == ApexLexer.COMMENT_CHANNEL) {
                assert lastStartIndex < token.getStartIndex()
                    : "Comments should be sorted";
                allCommentTokens.add(token);
            }

            if (checkForCommentSuppression && token.getType() == ApexLexer.LINE_COMMENT) {
                // check if it starts with the suppress marker
                String trimmedCommentText = token.getText().substring(2).trim();

                if (trimmedCommentText.startsWith(suppressMarker)) {
                    String userMessage = trimmedCommentText.substring(suppressMarker.length()).trim();
                    FileLocation loc = FileLocation.caret(
                        sourceCode.getFileId(),
                        token.getLine(),
                        token.getCharPositionInLine() + 1
                    );
                    suppressionComments.add(new SuppressionCommentImpl<>(() -> loc, userMessage));
                }
            }

            lastStartIndex = token.getStartIndex();
            token = lexer.nextToken();
        }

        return new CommentInformation(suppressionComments, allCommentTokens);
    }

    private static class CommentInformation {

        final Collection<SuppressionCommentWrapper> suppressionComments;
        final List<Integer> allCommentsByStartIndex;
        final List<ApexDocToken> docTokens;

        CommentInformation(Collection<SuppressionCommentWrapper> suppressMap, List<Token> allCommentTokens) {
            this.suppressionComments = suppressMap;
            this.docTokens = allCommentTokens.stream()
                .filter(token -> token.getType() == ApexLexer.DOC_COMMENT)
                .map(ApexDocToken::new)
                .collect(toList());
            this.allCommentsByStartIndex = new TokenListByStartIndex(new ArrayList<>(allCommentTokens));
        }
    }

    /**
     * List that maps comment tokens to their start index without copy.
     * This is used to implement a "binary search by key" routine which unfortunately isn't in the stdlib.
     *
     * <p>
     * Note that the provided token list must implement {@link RandomAccess}.
     */
    private static final class TokenListByStartIndex extends AbstractList<Integer> implements RandomAccess {

        private final List<Token> tokens;

        <T extends List<Token> & RandomAccess> TokenListByStartIndex(T tokens) {
            this.tokens = tokens;
        }

        @Override
        public Integer get(int index) {
            return tokens.get(index).getStartIndex();
        }

        @Override
        public int size() {
            return tokens.size();
        }
    }

    private static class ApexDocToken {
        AbstractApexNode nearestNode;
        Token token;

        ApexDocToken(Token token) {
            this.token = token;
        }
    }

    public Collection<SuppressionCommentWrapper> getSuppressMap() {
        return commentInfo.suppressionComments;
    }
}

1	/*
2	* BSD-style license; for more info see http://pmd.sourceforge.net/license.html
3	*/
4
5	package net.sourceforge.pmd.lang.apex.ast;
6
7	import static java.util.stream.Collectors.toList;
8
9	import java.util.AbstractList;
10	import java.util.ArrayList;
11	import java.util.Collection;
12	import java.util.Collections;
13	import java.util.List;
14	import java.util.RandomAccess;
15
16	import org.antlr.v4.runtime.BaseErrorListener;
17	import org.antlr.v4.runtime.CharStreams;
18	import org.antlr.v4.runtime.RecognitionException;
19	import org.antlr.v4.runtime.Recognizer;
20	import org.antlr.v4.runtime.Token;
21
22	import net.sourceforge.pmd.lang.ast.LexException;
23	import net.sourceforge.pmd.lang.ast.impl.SuppressionCommentImpl;
24	import net.sourceforge.pmd.lang.document.FileLocation;
25	import net.sourceforge.pmd.lang.document.TextDocument;
26	import net.sourceforge.pmd.lang.document.TextRegion;
27	import net.sourceforge.pmd.reporting.ViolationSuppressor.SuppressionCommentWrapper;
28
29	import io.github.apexdevtools.apexparser.ApexLexer;
30	import io.github.apexdevtools.apexparser.CaseInsensitiveInputStream;
31
32	final class ApexCommentBuilder {	1✔
33	private final TextDocument sourceCode;
34	private final CommentInformation commentInfo;
35
36	ApexCommentBuilder(TextDocument sourceCode, String suppressMarker) {	1✔
37	this.sourceCode = sourceCode;	1✔
38	this.commentInfo = extractInformationFromComments(sourceCode, suppressMarker);	1✔
39	}	1✔
40
41	public boolean containsComments(ASTCommentContainer commentContainer) {
42	if (!commentContainer.hasRealLoc()) {	1!
43	// Synthetic nodes don't have a location and can't have comments
44	return false;	×
45	}
46
47	TextRegion nodeRegion = commentContainer.getTextRegion();	1✔
48
49	// find the first comment after the start of the container node
50	int index = Collections.binarySearch(commentInfo.allCommentsByStartIndex, nodeRegion.getStartOffset());	1✔
51
52	// no exact hit found - this is expected: there is no comment token starting at
53	// the very same index as the node
54	assert index < 0 : "comment token is at the same position as non-comment token";	1!
55	// extract "insertion point"
56	index = ~index;	1✔
57
58	// now check whether the next comment after the node is still inside the node
59	if (index >= 0 && index < commentInfo.allCommentsByStartIndex.size()) {	1!
60	int commentStartIndex = commentInfo.allCommentsByStartIndex.get(index);	1✔
61	return nodeRegion.getStartOffset() < commentStartIndex	1!
62	&& nodeRegion.getEndOffset() >= commentStartIndex;	1✔
63	}
64	return false;	1✔
65	}
66
67	public void addFormalComments() {
68	for (ApexDocToken docToken : commentInfo.docTokens) {	1✔
69	AbstractApexNode parent = docToken.nearestNode;	1✔
70	if (parent != null) {	1✔
71	ASTFormalComment comment = new ASTFormalComment(docToken.token);	1✔
72	comment.calculateTextRegion(sourceCode);	1✔
73	parent.insertChild(comment, 0);	1✔
74	}
75	}	1✔
76	}	1✔
77
78	/**
79	* Only remembers the node, to which the comment could belong.
80	* Since the visiting order of the nodes does not match the source order,
81	* the nodes appearing later in the source might be visiting first.
82	* The correct node will then be visited afterwards, and since the distance
83	* to the comment is smaller, it overrides the remembered node.
84	*
85	* @param node the potential parent node, to which the comment could belong
86	*/
87	public void buildFormalComment(AbstractApexNode node) {
88	if (!node.hasRealLoc()) {	1✔
89	// Synthetic nodes such as "invoke" ASTMethod for trigger bodies don't have a location in the
90	// source code, since they are generated by the parser/compiler (see ApexTreeBuilder)
91	return;	1✔
92	}
93	// find the token, that appears as close as possible before the node
94	TextRegion nodeRegion = node.getTextRegion();	1✔
95	for (ApexDocToken docToken : commentInfo.docTokens) {	1✔
96	if (docToken.token.getStartIndex() > nodeRegion.getStartOffset()) {	1✔
97	// this and all remaining tokens are after the node
98	// so no need to check the remaining tokens.
99	break;	1✔
100	}
101
102	if (docToken.nearestNode == null	1✔
103	\|\| nodeRegion.compareTo(docToken.nearestNode.getTextRegion()) < 0) {	1✔
104
105	docToken.nearestNode = node;	1✔
106	}
107	}	1✔
108	}	1✔
109
110	private static CommentInformation extractInformationFromComments(TextDocument sourceCode, String suppressMarker) {
111	String source = sourceCode.getText().toString();	1✔
112	ApexLexer lexer = new ApexLexer(new CaseInsensitiveInputStream(CharStreams.fromString(source)));	1✔
113	lexer.removeErrorListeners();	1✔
114	lexer.addErrorListener(new BaseErrorListener() {	1✔
115	@Override
116	public void syntaxError(Recognizer<?, ?> recognizer, Object offendingSymbol, int line, int charPositionInLine, String msg, RecognitionException e) {
117	throw new LexException(line, charPositionInLine, sourceCode.getFileId(), msg, e);	×
118	}
119	});
120
121	List<Token> allCommentTokens = new ArrayList<>();	1✔
122	List<SuppressionCommentWrapper> suppressionComments = new ArrayList<>();	1✔
123	int lastStartIndex = -1;	1✔
124	Token token = lexer.nextToken();	1✔
125
126	boolean checkForCommentSuppression = suppressMarker != null;	1!
127
128	while (token.getType() != Token.EOF) {	1✔
129	// Keep track of all comment tokens
130	if (token.getChannel() == ApexLexer.COMMENT_CHANNEL) {	1✔
131	assert lastStartIndex < token.getStartIndex()	1!
132	: "Comments should be sorted";
133	allCommentTokens.add(token);	1✔
134	}
135
136	if (checkForCommentSuppression && token.getType() == ApexLexer.LINE_COMMENT) {	1!
137	// check if it starts with the suppress marker
138	String trimmedCommentText = token.getText().substring(2).trim();	1✔
139
140	if (trimmedCommentText.startsWith(suppressMarker)) {	1✔
141	String userMessage = trimmedCommentText.substring(suppressMarker.length()).trim();	1✔
142	FileLocation loc = FileLocation.caret(	1✔
143	sourceCode.getFileId(),	1✔
144	token.getLine(),	1✔
145	token.getCharPositionInLine() + 1	1✔
146	);
147	suppressionComments.add(new SuppressionCommentImpl<>(() -> loc, userMessage));	1✔
148	}
149	}
150
151	lastStartIndex = token.getStartIndex();	1✔
152	token = lexer.nextToken();	1✔
153	}
154
155	return new CommentInformation(suppressionComments, allCommentTokens);	1✔
156	}
157
158	private static class CommentInformation {
159
160	final Collection<SuppressionCommentWrapper> suppressionComments;
161	final List<Integer> allCommentsByStartIndex;
162	final List<ApexDocToken> docTokens;
163
164	CommentInformation(Collection<SuppressionCommentWrapper> suppressMap, List<Token> allCommentTokens) {	1✔
165	this.suppressionComments = suppressMap;	1✔
166	this.docTokens = allCommentTokens.stream()	1✔
167	.filter(token -> token.getType() == ApexLexer.DOC_COMMENT)	1✔
168	.map(ApexDocToken::new)	1✔
169	.collect(toList());	1✔
170	this.allCommentsByStartIndex = new TokenListByStartIndex(new ArrayList<>(allCommentTokens));	1✔
171	}	1✔
172	}
173
174	/**
175	* List that maps comment tokens to their start index without copy.
176	* This is used to implement a "binary search by key" routine which unfortunately isn't in the stdlib.
177	*
178	* <p>
179	* Note that the provided token list must implement {@link RandomAccess}.
180	*/
181	private static final class TokenListByStartIndex extends AbstractList<Integer> implements RandomAccess {
182
183	private final List<Token> tokens;
184
185	<T extends List<Token> & RandomAccess> TokenListByStartIndex(T tokens) {	1✔
186	this.tokens = tokens;	1✔
187	}	1✔
188
189	@Override
190	public Integer get(int index) {
191	return tokens.get(index).getStartIndex();	1✔
192	}
193
194	@Override
195	public int size() {
196	return tokens.size();	1✔
197	}
198	}
199
200	private static class ApexDocToken {
201	AbstractApexNode nearestNode;
202	Token token;
203
204	ApexDocToken(Token token) {	1✔
205	this.token = token;	1✔
206	}	1✔
207	}
208
209	public Collection<SuppressionCommentWrapper> getSuppressMap() {
210	return commentInfo.suppressionComments;	1✔
211	}
212	}

pmd / pmd / 380

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous