diff --git a/CHANGELOG.md b/CHANGELOG.md index 4e1246b6..c3833e30 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -51,6 +51,7 @@ - Используется аннотация &ИзменениеИКонтроль вместо &Вместо - НСтр формат строкового литерала - Использование булевного параметра обработчика события +- Использование только дефис-минуса в документирующем комментарии #### Запросы diff --git a/bundles/com.e1c.v8codestyle.bsl/markdown/doc-comment-use-minus.md b/bundles/com.e1c.v8codestyle.bsl/markdown/doc-comment-use-minus.md new file mode 100644 index 00000000..60d844a0 --- /dev/null +++ b/bundles/com.e1c.v8codestyle.bsl/markdown/doc-comment-use-minus.md @@ -0,0 +1,35 @@ +# Use only hyphen-minus in documentation comment + +In Description of Documentation comment model should use only hyphen-minus symbol instead of usual hyphen or different dashes. + +This check analyze wrong "minus" only in first text part of description which goes after field declaration to catch possible wrong parsing of the documentation comment model. + +## Noncompliant Code Example + +```bsl +// Parameters: +// Parameters – Structure - first is middle-dash and second is minus: +// * Key1 - Number ⸺ incorrect long dash +Procedure NonComplaint(Parameters) Export + // empty +EndProcedure +``` + + +## Compliant Solution + + +```bsl +// Parameters: +// Parameters - Structure - both are minus: +// * Key1 - Number - used correct minus +Procedure Complaint(Parameters) Export + // empty +EndProcedure +``` + +## See + + +- [Wikipedia: Hyphen](https://en.wikipedia.org/wiki/Hyphen) +- [Wikipedia: Dash](https://en.wikipedia.org/wiki/Dash) diff --git a/bundles/com.e1c.v8codestyle.bsl/markdown/ru/doc-comment-use-minus.md b/bundles/com.e1c.v8codestyle.bsl/markdown/ru/doc-comment-use-minus.md new file mode 100644 index 00000000..451a6e4f --- /dev/null +++ b/bundles/com.e1c.v8codestyle.bsl/markdown/ru/doc-comment-use-minus.md @@ -0,0 +1,33 @@ +# Использование только дефис-минуса в документирующем комментарии + +В Описании в модели документирующего комментария необходимо использовать только символ дефис-минус вместо обычного дефиса или различных вариантов тире. + +Эта проверка анализирует неправильне "минсы" в первом текстовом элементе в описании, идущем после декларации поля, чтобы найти возвожное неправильное построение модели документирующего комментария. + +## Неправильно + +```bsl +// Параметры: +// Параметры – Структура - первый это "среднее тире" а второй это "минус": +// * Ключ1 - Число ⸺ некорректное длинное тире +Процедура NonComplaint(Параметры) Экспорт + // пустая +КонецПроцедуры +``` + +## Правильно + + +```bsl +// Параметры: +// Параметры - Структура - оба использованы минусы: +// * Ключ1 - Число - использованы корректные дефис-минусы +Процедура Complaint(Параметры) Экспорт + // пустая +КонецПроцедуры +``` + +## См. + +- [Википедия: Дефис](https://ru.wikipedia.org/wiki/Дефис) +- [Википедия: Тире](https://ru.wikipedia.org/wiki/Тире) diff --git a/bundles/com.e1c.v8codestyle.bsl/plugin.xml b/bundles/com.e1c.v8codestyle.bsl/plugin.xml index 38024bc5..6453279d 100644 --- a/bundles/com.e1c.v8codestyle.bsl/plugin.xml +++ b/bundles/com.e1c.v8codestyle.bsl/plugin.xml @@ -104,6 +104,10 @@ category="com.e1c.v8codestyle.bsl" class="com.e1c.v8codestyle.internal.bsl.ExecutableExtensionFactory:com.e1c.v8codestyle.bsl.check.EventHandlerBooleanParamCheck"> + + diff --git a/bundles/com.e1c.v8codestyle.bsl/src/com/e1c/v8codestyle/bsl/comment/check/DocCommentUseMinusCheck.java b/bundles/com.e1c.v8codestyle.bsl/src/com/e1c/v8codestyle/bsl/comment/check/DocCommentUseMinusCheck.java new file mode 100644 index 00000000..9ab1efa5 --- /dev/null +++ b/bundles/com.e1c.v8codestyle.bsl/src/com/e1c/v8codestyle/bsl/comment/check/DocCommentUseMinusCheck.java @@ -0,0 +1,132 @@ +/******************************************************************************* + * Copyright (C) 2021, 1C-Soft LLC and others. + * + * This program and the accompanying materials are made + * available under the terms of the Eclipse Public License 2.0 + * which is available at https://www.eclipse.org/legal/epl-2.0/ + * + * SPDX-License-Identifier: EPL-2.0 + * + * Contributors: + * 1C-Soft LLC - initial API and implementation + *******************************************************************************/ +package com.e1c.v8codestyle.bsl.comment.check; + +import java.text.MessageFormat; +import java.util.regex.Matcher; +import java.util.regex.Pattern; + +import org.eclipse.core.runtime.IProgressMonitor; + +import com._1c.g5.v8.dt.bsl.documentation.comment.BslDocumentationComment; +import com._1c.g5.v8.dt.bsl.documentation.comment.BslDocumentationComment.Description; +import com._1c.g5.v8.dt.bsl.documentation.comment.IDescriptionPart; +import com._1c.g5.v8.dt.bsl.documentation.comment.TextPart; +import com.e1c.g5.v8.dt.bsl.check.DocumentationCommentBasicDelegateCheck; +import com.e1c.g5.v8.dt.check.CheckComplexity; +import com.e1c.g5.v8.dt.check.ICheckParameters; +import com.e1c.g5.v8.dt.check.settings.IssueSeverity; +import com.e1c.g5.v8.dt.check.settings.IssueType; + +/** + * In Description of Documentation comment model should use only hyphen-minus symbol instead of usual hyphen + * or different dashes. This check analyze wrong "minus" only in first text part of description which goes after field + * declaration to catch possible wrong parsing of the documentation comment model. + * + * @author Dmitriy Marmyshev + */ +public class DocCommentUseMinusCheck + extends DocumentationCommentBasicDelegateCheck +{ + + private static final String CHECK_ID = "doc-comment-use-minus"; //$NON-NLS-1$ + + /** The pattern to find wrong hyphen symbols: [–—‒―⸺⸻‑‐]+ + * Unicode symbols are forbidden: + * 0x2013 - middle dash – + * 0x2014 - long dash — + * 0x2012 - digital dash ‒ + * 0x2015 - horizontal line ― + * 0x2E3A - double dash ⸺ + * 0x2E3B - triple dash ⸻ + * 0x2010 - hyphen ‐ + * 0x2011 - solid-hyphen ‑ + * + * Acceptable only hyphen-minus: 0x002D - + */ + private static final Pattern WRONG_HYPHEN = Pattern.compile("[–—‒―⸺⸻‑‐]+"); //$NON-NLS-1$ + + private static final int SHOW_PREV_SYMBOLS = 7; + + @Override + public String getCheckId() + { + return CHECK_ID; + } + + @Override + protected void configureCheck(CheckConfigurer builder) + { + builder.title(Messages.DocCommentUseMinusCheck_title) + .description(Messages.DocCommentUseMinusCheck_description) + .complexity(CheckComplexity.NORMAL) + .severity(IssueSeverity.MAJOR) + .issueType(IssueType.ERROR) + .delegate(Description.class); + } + + @Override + protected void checkDocumentationCommentObject(IDescriptionPart object, BslDocumentationComment root, + DocumentationCommentResultAcceptor resultAceptor, ICheckParameters parameters, IProgressMonitor monitor) + { + if (object.getParent() instanceof BslDocumentationComment) + { + // Should not restrict any "wrong-minus" symbols in description of root + return; + } + + Description descr = (Description)object; + + for (IDescriptionPart part : descr.getParts()) + { + if (part instanceof TextPart) + { + TextPart textPart = (TextPart)part; + String text = textPart.getText(); + Matcher matcher = WRONG_HYPHEN.matcher(text); + int previous = 0; + while (matcher.find()) + { + int start = matcher.start(); + int end = matcher.end(); + + int offset = textPart.getOffset() + start; + int lenth = end - start; + if ((start - previous) > SHOW_PREV_SYMBOLS) + { + start = start - SHOW_PREV_SYMBOLS; + } + else + { + start = previous; + } + String symbols = text.substring(start, end); + + previous = end; + + String message = MessageFormat.format( + Messages.DocCommentUseMinusCheck_Only_hyphen_minus_symbol_is_allowed_in_doc_comment_but_found_0, + symbols); + + resultAceptor.addIssue(message, textPart.getLineNumber(), offset, lenth); + } + } + else + { + // analyze only first text part + break; + } + } + } + +} diff --git a/bundles/com.e1c.v8codestyle.bsl/src/com/e1c/v8codestyle/bsl/comment/check/Messages.java b/bundles/com.e1c.v8codestyle.bsl/src/com/e1c/v8codestyle/bsl/comment/check/Messages.java new file mode 100644 index 00000000..5a28eee7 --- /dev/null +++ b/bundles/com.e1c.v8codestyle.bsl/src/com/e1c/v8codestyle/bsl/comment/check/Messages.java @@ -0,0 +1,37 @@ +/******************************************************************************* + * Copyright (C) 2021, 1C-Soft LLC and others. + * + * This program and the accompanying materials are made + * available under the terms of the Eclipse Public License 2.0 + * which is available at https://www.eclipse.org/legal/epl-2.0/ + * + * SPDX-License-Identifier: EPL-2.0 + * + * Contributors: + * 1C-Soft LLC - initial API and implementation + *******************************************************************************/ +package com.e1c.v8codestyle.bsl.comment.check; + +import org.eclipse.osgi.util.NLS; + +/** + * @author Dmitriy Marmyshev + * + */ +final class Messages + extends NLS +{ + private static final String BUNDLE_NAME = "com.e1c.v8codestyle.bsl.comment.check.messages"; //$NON-NLS-1$ + public static String DocCommentUseMinusCheck_description; + public static String DocCommentUseMinusCheck_Only_hyphen_minus_symbol_is_allowed_in_doc_comment_but_found_0; + public static String DocCommentUseMinusCheck_title; + static + { + // initialize resource bundle + NLS.initializeMessages(BUNDLE_NAME, Messages.class); + } + + private Messages() + { + } +} diff --git a/bundles/com.e1c.v8codestyle.bsl/src/com/e1c/v8codestyle/bsl/comment/check/messages.properties b/bundles/com.e1c.v8codestyle.bsl/src/com/e1c/v8codestyle/bsl/comment/check/messages.properties new file mode 100644 index 00000000..4eb73351 --- /dev/null +++ b/bundles/com.e1c.v8codestyle.bsl/src/com/e1c/v8codestyle/bsl/comment/check/messages.properties @@ -0,0 +1,19 @@ +#Generated by ResourceBundle Editor (http://essiembre.github.io/eclipse-rbe/) +############################################################################### +# Copyright (C) 2021, 1C-Soft LLC and others. +# +# This program and the accompanying materials are made +# available under the terms of the Eclipse Public License 2.0 +# which is available at https://www.eclipse.org/legal/epl-2.0/ +# +# SPDX-License-Identifier: EPL-2.0 +# +# Contributors: +# 1C-Soft LLC - initial API and implementation +############################################################################### + +DocCommentUseMinusCheck_Only_hyphen_minus_symbol_is_allowed_in_doc_comment_but_found_0=Only hyphen-minus symbol is allowed in documentation comment, but found: "{0}" + +DocCommentUseMinusCheck_description = Use only hyphen-minus in documentation comment + +DocCommentUseMinusCheck_title = Use only hyphen-minus in documentation comment diff --git a/bundles/com.e1c.v8codestyle.bsl/src/com/e1c/v8codestyle/bsl/comment/check/messages_ru.properties b/bundles/com.e1c.v8codestyle.bsl/src/com/e1c/v8codestyle/bsl/comment/check/messages_ru.properties new file mode 100644 index 00000000..862528de --- /dev/null +++ b/bundles/com.e1c.v8codestyle.bsl/src/com/e1c/v8codestyle/bsl/comment/check/messages_ru.properties @@ -0,0 +1,19 @@ +#Generated by ResourceBundle Editor (http://essiembre.github.io/eclipse-rbe/) +############################################################################### +# Copyright (C) 2021, 1C-Soft LLC and others. +# +# This program and the accompanying materials are made +# available under the terms of the Eclipse Public License 2.0 +# which is available at https://www.eclipse.org/legal/epl-2.0/ +# +# SPDX-License-Identifier: EPL-2.0 +# +# Contributors: +# 1C-Soft LLC - initial API and implementation +############################################################################### + +DocCommentUseMinusCheck_Only_hyphen_minus_symbol_is_allowed_in_doc_comment_but_found_0 = Только символ дефис-минуса разрешено использовать в документирующем комментарии, но найдено: "{0}" + +DocCommentUseMinusCheck_description = Использование только дефис-минуса в документирующем комментарии + +DocCommentUseMinusCheck_title = Использование только дефис-минуса в документирующем комментарии diff --git a/tests/com.e1c.v8codestyle.bsl.itests/resources/doc-comment-use-minus.bsl b/tests/com.e1c.v8codestyle.bsl.itests/resources/doc-comment-use-minus.bsl new file mode 100644 index 00000000..c7598726 --- /dev/null +++ b/tests/com.e1c.v8codestyle.bsl.itests/resources/doc-comment-use-minus.bsl @@ -0,0 +1,14 @@ + +// Parameters: +// Parameters – Structure - first is middle-dash and second is minus: +// * Key1 - Number ⸺ incorrect long dash +Procedure NonComplaint(Parameters) Export + // empty +EndProcedure + +// Parameters: +// Parameters - Structure - both are minus: +// * Key1 - Number - used correct minus +Procedure Complaint(Parameters) Export + // empty +EndProcedure diff --git a/tests/com.e1c.v8codestyle.bsl.itests/src/com/e1c/v8codestyle/bsl/comment/check/itests/DocCommentUseMinusCheckTest.java b/tests/com.e1c.v8codestyle.bsl.itests/src/com/e1c/v8codestyle/bsl/comment/check/itests/DocCommentUseMinusCheckTest.java new file mode 100644 index 00000000..93036aaa --- /dev/null +++ b/tests/com.e1c.v8codestyle.bsl.itests/src/com/e1c/v8codestyle/bsl/comment/check/itests/DocCommentUseMinusCheckTest.java @@ -0,0 +1,58 @@ +/******************************************************************************* + * Copyright (C) 2021, 1C-Soft LLC and others. + * + * This program and the accompanying materials are made + * available under the terms of the Eclipse Public License 2.0 + * which is available at https://www.eclipse.org/legal/epl-2.0/ + * + * SPDX-License-Identifier: EPL-2.0 + * + * Contributors: + * 1C-Soft LLC - initial API and implementation + *******************************************************************************/ +package com.e1c.v8codestyle.bsl.comment.check.itests; + +import static org.junit.Assert.assertEquals; + +import java.util.List; + +import org.junit.Test; + +import com._1c.g5.v8.dt.validation.marker.IExtraInfoKeys; +import com._1c.g5.v8.dt.validation.marker.Marker; +import com.e1c.v8codestyle.bsl.check.itests.AbstractSingleModuleTestBase; +import com.e1c.v8codestyle.bsl.comment.check.DocCommentUseMinusCheck; + +/** + * Tests for {@link DocCommentUseMinusCheck} check. + * + * @author Dmitriy Marmyshev + */ +public class DocCommentUseMinusCheckTest + extends AbstractSingleModuleTestBase +{ + + public DocCommentUseMinusCheckTest() + { + super(DocCommentUseMinusCheck.class); + } + + /** + * Test the documentation comment used correct hyphen-minus + * + * @throws Exception the exception + */ + @Test + public void testInvalidMinusUsed() throws Exception + { + updateModule(FOLDER_RESOURCE + "doc-comment-use-minus.bsl"); + + List markers = getModuleMarkers(); + assertEquals(2, markers.size()); + Marker marker = markers.get(0); + assertEquals("3", marker.getExtraInfo().get(IExtraInfoKeys.TEXT_EXTRA_INFO_LINE_KEY)); + marker = markers.get(1); + assertEquals("4", marker.getExtraInfo().get(IExtraInfoKeys.TEXT_EXTRA_INFO_LINE_KEY)); + + } +}