Skip to content

Commit 0dd63ed

Browse files
Mirletticlaude
andauthored
feat(#998): add comment-starts-with-article lint (#1005)
Adds a new XSL-based lint that reports a warning when an object's comment starts with an article ("a", "an", or "the"). Such articles add no information and make documentation needlessly verbose. The check is case-insensitive and only matches an article followed by whitespace, so words that merely begin with the same letters (e.g. "Another", "Theory", "Andes") are not flagged. Includes the motive document and YAML packs covering the "a", "an" and "the" articles, a clean comment, and the article-prefix edge cases. Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 99ca046 commit 0dd63ed

7 files changed

Lines changed: 114 additions & 0 deletions

File tree

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!--
3+
* SPDX-FileCopyrightText: Copyright (c) 2016-2026 Objectionary.com
4+
* SPDX-License-Identifier: MIT
5+
-->
6+
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:eo="https://www.eolang.org" id="comment-starts-with-article" version="2.0">
7+
<xsl:import href="/org/eolang/funcs/lineno.xsl"/>
8+
<xsl:import href="/org/eolang/funcs/defect-context.xsl"/>
9+
<xsl:output encoding="UTF-8" method="xml"/>
10+
<xsl:template match="/">
11+
<defects>
12+
<xsl:for-each select="/object/comments/comment[matches(., '^(a|an|the)\s', 'i')]">
13+
<xsl:element name="defect">
14+
<xsl:variable name="line" select="eo:lineno(@line)"/>
15+
<xsl:attribute name="line">
16+
<xsl:value-of select="$line"/>
17+
</xsl:attribute>
18+
<xsl:if test="$line = '0'">
19+
<xsl:attribute name="context">
20+
<xsl:value-of select="eo:defect-context(.)"/>
21+
</xsl:attribute>
22+
</xsl:if>
23+
<xsl:attribute name="severity">
24+
<xsl:text>warning</xsl:text>
25+
</xsl:attribute>
26+
<xsl:text>The comment starts with an article ("a", "an", or "the"), which is redundant and should be removed</xsl:text>
27+
</xsl:element>
28+
</xsl:for-each>
29+
</defects>
30+
</xsl:template>
31+
</xsl:stylesheet>
Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Comment Starts With Article
2+
3+
Comments should not start with an article, such as `a`, `an`, or `the`.
4+
An article at the beginning of a comment adds no information and makes
5+
the documentation more verbose than necessary.
6+
7+
Incorrect:
8+
9+
```eo
10+
# The object that calculates the sum.
11+
[] > foo
12+
42 > @
13+
```
14+
15+
Correct:
16+
17+
```eo
18+
# Object that calculates the sum.
19+
[] > foo
20+
42 > @
21+
```
22+
23+
The check is case-insensitive, so `A`, `An`, and `The` are flagged as
24+
well. Words that merely begin with the same letters as an article, such
25+
as `Another` or `Theory`, are not affected.
Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# SPDX-FileCopyrightText: Copyright (c) 2016-2026 Objectionary.com
2+
# SPDX-License-Identifier: MIT
3+
---
4+
sheets:
5+
- /org/eolang/lints/comments/comment-starts-with-article.xsl
6+
asserts:
7+
- /defects[count(defect[@severity='warning'])=0]
8+
input: |
9+
# Object that calculates the sum of two numbers.
10+
[] > foo
11+
42 > @
Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# SPDX-FileCopyrightText: Copyright (c) 2016-2026 Objectionary.com
2+
# SPDX-License-Identifier: MIT
3+
---
4+
sheets:
5+
- /org/eolang/lints/comments/comment-starts-with-article.xsl
6+
asserts:
7+
- /defects[count(defect[@severity='warning'])=0]
8+
input: |
9+
# Another object that wraps a theory of numbers.
10+
[] > foo
11+
42 > @
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# SPDX-FileCopyrightText: Copyright (c) 2016-2026 Objectionary.com
2+
# SPDX-License-Identifier: MIT
3+
---
4+
sheets:
5+
- /org/eolang/lints/comments/comment-starts-with-article.xsl
6+
asserts:
7+
- /defects[count(defect[@severity='warning'])=1]
8+
- /defects/defect[@line='2']
9+
input: |
10+
# a simple object that does nothing useful.
11+
[] > foo
12+
42 > @
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# SPDX-FileCopyrightText: Copyright (c) 2016-2026 Objectionary.com
2+
# SPDX-License-Identifier: MIT
3+
---
4+
sheets:
5+
- /org/eolang/lints/comments/comment-starts-with-article.xsl
6+
asserts:
7+
- /defects[count(defect[@severity='warning'])=1]
8+
- /defects/defect[@line='2']
9+
input: |
10+
# An object that represents a single user.
11+
[] > foo
12+
42 > @
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# SPDX-FileCopyrightText: Copyright (c) 2016-2026 Objectionary.com
2+
# SPDX-License-Identifier: MIT
3+
---
4+
sheets:
5+
- /org/eolang/lints/comments/comment-starts-with-article.xsl
6+
asserts:
7+
- /defects[count(defect[@severity='warning'])=1]
8+
- /defects/defect[@line='2']
9+
input: |
10+
# The object that calculates the sum.
11+
[] > foo
12+
42 > @

0 commit comments

Comments
 (0)