Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[#224] Add description for multiline puzzle #237

Merged
merged 12 commits into from Feb 4, 2024
Merged

[#224] Add description for multiline puzzle #237

Changes from 1 commit
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
2f83a39
[#224] Add description for multiline puzzle and remove unsupported fo…
pnatashap Jan 21, 2024
8e26e6f
Update README.md
pnatashap Jan 22, 2024
a2acecf
Update README.md
pnatashap Jan 22, 2024
0c10776
[#224] Change space symbol to backslash for newline
pnatashap Jan 27, 2024
194a4ba
[#224] Add a test for javadoc and small change
pnatashap Jan 27, 2024
a71e657
Update README.md
pnatashap Jan 31, 2024
291030b
[#238] Add another example for ticket id's
pnatashap Feb 1, 2024
bb3f370
[#238] Sink with master and update codecov-action (just released)
pnatashap Feb 1, 2024
438d324
[#238] Add a test for last empty line
pnatashap Feb 1, 2024
4e4fe39
[#238] Return back steps
pnatashap Feb 1, 2024
53b9be5
[#238] Flag to fail Cucumber tests in case of missing steps
pnatashap Feb 1, 2024
317b976
[#238] Changed description
pnatashap Feb 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
43 changes: 36 additions & 7 deletions README.md
View file
Open in desktop
Expand Up @@ -146,6 +146,10 @@ Example:
* @todo #234:15m/DEV This is something to do later
* in one of the next releases. I can't figure out
* how to implement it now, that's why the puzzle.
* The text can be so long, as needed, just use
* the same anount of spaces, as the second line.
* This text will be not a part of the puzzle, as
* has less spaces.
pnatashap marked this conversation as resolved.
Show resolved Hide resolved
*/
void sendEmail() {
throw new UnsupportedOperationException();
Expand All @@ -172,13 +176,11 @@ as long as you have one of the 3 supported keywords right in front
of the mandatory marker):

```
// @todo #224
/* @todo #TEST-13 */
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why it was removed?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is not supported in the code, there is only a logic to remove prefix, but no logic to remove any kinds of symbols from the end

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this case, I'd suggest to fix/improve support for such type of comments instead of removing it from documentation.

Copy link
Contributor Author

@pnatashap pnatashap Jan 27, 2024 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is a bug about it #225
I think it is better to remove it now and return it back after fix

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pnatashap If we remove this examples, I believe we have to remove TEST-13 and 42 from the next sentence too:

224, TEST-13, 55, 67, 678, 1, and 42 are the IDs of the tickets these puzzles are coming from.

# @todo #55:45min
@todo #67/DES
;; @todo #678:40m/DEV
// TODO: #1:30min
(* TODO #42 *)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The same: why it has been removed?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is not supported in the code, there is only a logic to remove prefix, but no logic to remove any kinds of symbols from the end

// @todo #224 Puzzle description
# @todo #55:45min Puzzle description
@todo #67/DES Puzzle description
;; @todo #678:40m/DEV Puzzle description
// TODO: #1:30min Puzzle description
```

Here `DES` and `DEV` are the roles of people who must fix that puzzles;
Expand All @@ -192,6 +194,33 @@ us to build a hierarchical dependency tree of all puzzles, like
for example. Technically, of course, you can abuse the system
and put a dummy `#1` marker everywhere.

### Multiline examples

```xml
<!--
~ if comment should be started and closed by special symbols, then place them in
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pnatashap What Is "prefix" here? ~ ? I haven't found the definition of "prefix" in the README file.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It can be used to decorate text, not required, but for there is no restrictions about the prefix, it should be just equal for all text. So it is just an example

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pnatashap, maybe we can add this to the documentation? I mean, we can state that the "prefix" is a symbol that can be used to decorate text; it isn't required. And provide some examples.

Moreover, I would suggest adding some headers or small - one-sentence descriptions to these code examples:

  1. "...Prefix definition... Here we ignore the prefix, and only one puzzle will be created."
  2. "We can also use the \ symbol to connect multiline puzzles."

What do you think?

~ a separate lines without any text
~ And any symbols can be used as a prefix, it will be excluded from the text
pnatashap marked this conversation as resolved.
Show resolved Hide resolved
~
~ @todo #34 Description can not be created in one line with comment
~ symbols. Just use at least the same amount of the spaces, as on the first line.
-->
```

```java
/**
* @todo #36 Multiline text can use the same prefix in all lines or the same
* amount of spaces.
So this will be added to the puzzle description. If you want to divide the
* puzzle by empty line, just add a space to that line
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMHO we should reconsider and improve this rule. Using a trailing space for making decisions isn't good.
First, it's non-obvious.
Second, it's invisible, so it's really hard to catch such issues on code review.
Third, users may want to run auto-formatting tools, that can remove such "noise". In this case, users will face a massive close and creation of the issues.

How about using a backslash? Like this:

/**
 * @todo #36 Multiline text can use the same prefix in all lines or the same 
 *  amount of spaces.
    So this will be added to the puzzle description. If you want to divide the 
 *  puzzle by empty line, just add a backslash to that line
 *  \
 *  and continue the text after.
 *
 *  This line is not part of the puzzle, because the line before contains less
 *  spaces then the second line.
 */

@yegor256 WDYT?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pnatashap @php-coder indeed, a "blind" space at the end of a line is provocation of a mistake

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good symbol should be clear enough for developers.
Also will check if it works for second line as described in #163

*
* and continue the text after.
*
* This line is not part of the puzzle, because the line before contains less
* spaces then the second line.
*/
```

## How to Configure Rules?

You can specify post-parsing rules for your puzzles, in command line,
Expand Down