-
Notifications
You must be signed in to change notification settings - Fork 26
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.
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
[#224] Add description for multiline puzzle #237
Changes from all commits
2f83a39
8e26e6f
a2acecf
0c10776
194a4ba
a71e657
291030b
bb3f370
438d324
4e4fe39
53b9be5
317b976
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -116,6 +116,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 | ||
* it has less spaces. | ||
*/ | ||
void sendEmail() { | ||
throw new UnsupportedOperationException(); | ||
|
@@ -142,18 +146,16 @@ as long as you have one of the 3 supported keywords right in front | |
of the mandatory marker): | ||
|
||
``` | ||
// @todo #224 | ||
/* @todo #TEST-13 */ | ||
# @todo #55:45min | ||
@todo #67/DES | ||
;; @todo #678:40m/DEV | ||
// TODO: #1:30min | ||
(* TODO #42 *) | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The same: why it has been removed? There was a problem hiding this comment. Choose a reason for hiding this commentThe 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: #TEST-21:30min Puzzle description | ||
``` | ||
|
||
Here `DES` and `DEV` are the roles of people who must fix that puzzles; | ||
`45min` and `40m` is the amount of time the puzzle should take; | ||
`224`, `TEST-13`, `55`, `67`, `678`, `1`, and `42` are the IDs of the tickets | ||
`224`, `55`, `67`, `678` and `TEST-21` are the IDs of the tickets | ||
these puzzles are coming from. | ||
|
||
Markers are absolutely necessary for all puzzles, because they allow | ||
|
@@ -162,6 +164,43 @@ 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 | ||
|
||
For multiline puzzles there are two important things: | ||
- **prefix** - any optional text followed by space before puzzle keyword (todo). | ||
It should be the same for all lines of puzzle description. | ||
- \ symbol can be used to logically divide puzzle description. | ||
prefix should be presented with it. | ||
|
||
Examples: | ||
|
||
```xml | ||
<!-- | ||
~ if comment should be started and closed by special symbols, then place them in | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @pnatashap What Is "prefix" here? There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 There was a problem hiding this comment. Choose a reason for hiding this commentThe 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:
What do you think? |
||
~ a separate lines | ||
~ Any symbol can be used as a prefix, it will be excluded from the text. | ||
~ But do not forget about the space before puzzle keyword. | ||
~ | ||
~ @todo #34 Description can be as long as needed. | ||
~ Just use at least the same amount of the spaces, as on the first line. | ||
~ It will be added to description. | ||
--> | ||
``` | ||
|
||
```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 logically by empty line, just add a backspace to that line | ||
* \ | ||
* and continue the text after. | ||
* | ||
* This line is not part of the puzzle, because the line before does not contain | ||
* prefix. | ||
*/ | ||
``` | ||
|
||
## How to Configure Rules? | ||
|
||
You can specify post-parsing rules for your puzzles, in command line, | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -2,7 +2,7 @@ | |
// @todo #44 This puzzle | ||
// consists | ||
// of | ||
// | ||
// \ | ||
// two | ||
// paragraphs | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why it was removed?
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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
and42
from the next sentence too: