METRON-1308: Fix Metron Documentation #836
Conversation
| @@ -257,7 +258,7 @@ In the core language functions, we support basic functional programming primitiv | |||
| * Description: Adds an element to the bloom filter passed in | |||
| * Input: | |||
| * bloom - The bloom filter | |||
| * value* - The values to add | |||
| * value\*? - The values to add | |||
There was a problem hiding this comment.
Why does this have an *?
There was a problem hiding this comment.
It's a repetition symbol, so it implies you can have any number of values.
There was a problem hiding this comment.
Okay, I get your intent now. It was being suppressed before because it wasn't escaped, I will try to make it more obvious.
| @@ -748,7 +728,7 @@ In the core language functions, we support basic functional programming primitiv | |||
| ### `MULTISET_INIT` | |||
| * Description: Creates an empty multiset, which is a map associating objects to their instance counts. | |||
| * Input: | |||
| * input? - An initialization of the multiset | |||
| * input?? - An initialization of the multiset | |||
There was a problem hiding this comment.
Why does this have a ??
There was a problem hiding this comment.
? implies it may be included or not, like regex
There was a problem hiding this comment.
Gotcha, okay. I think I would prefer something like (optional), what do you think?
| @@ -849,7 +829,7 @@ In the core language functions, we support basic functional programming primitiv | |||
| ### `SET_INIT` | |||
| * Description: Creates an new set | |||
| * Input: | |||
| * input? - An initialization of the set | |||
| * input?? - An initialization of the set | |||
There was a problem hiding this comment.
Why does this have a ??
| @@ -1034,15 +1035,15 @@ In the core language functions, we support basic functional programming primitiv | |||
| See [python](https://docs.python.org/3/library/functions.html#zip) | |||
| and [wikipedia](https://en.wikipedia.org/wiki/Convolution_(computer_science)) for more context. | |||
| * Input: | |||
| * list* - Lists to zip. | |||
| * list\*? - Lists to zip. | |||
There was a problem hiding this comment.
Why does this have an *?
| * Returns: The zip of the lists. The returned list is the min size of all the lists. e.g. `ZIP( [ 1, 2 ], [ 3, 4, 5] ) == [ [1, 3], [2, 4] ]` | ||
|
|
||
| ### `ZIP_LONGEST` | ||
| * Description: Zips lists into a single list where the ith element is an list containing the ith items from the constituent lists. | ||
| See [python](https://docs.python.org/3/library/itertools.html#itertools.zip_longest) | ||
| and [wikipedia](https://en.wikipedia.org/wiki/Convolution_(computer_science)) for more context. | ||
| * Input: | ||
| * list* - Lists to zip. | ||
| * list\*? - Lists to zip. |
There was a problem hiding this comment.
Why does this have an *?
|
So, answering your questions en-masse we use the following similar to how they exist in regex:
In retrospect, this may not be as obvious as it seemed at the time. Think we need a key that indicates this? ;) |
|
I think I'm more of a fan of being explicit than providing a key, given this only happens a few times through the whole doc. Also, like I mentioned, the *s are being suppressed, so they're not actually in either form of the documentation (here and here) which we've seen bite us numerous times in the past in our docs. |
|
I just took a stab at an update, @cestella can you take a look when you get a second |
JonZeolla
changed the title
|
Since we have a release coming up, I won't have time to do any additional documentation review past what I've already done, so I'm game to merge this in as it currently sits. @cestella have you had a chance to review? |
|
@cestella I know you were out recently, just wanted to bring this one to the top of your inbox. Would like to have this in the upcoming release, but also want to get your input. |
|
+1 I like this @JonZeolla. This reads more clearly IMHO. |
|
Merged master, ran tests successfully, built site-books and did some clicking around. Going to merge. |
Contributor Comments
More documentation fixes - work in progress but looking to get a review of some findings (see comments)
Pull Request Checklist
Thank you for submitting a contribution to Apache Metron.
Please refer to our Development Guidelines for the complete guide to follow for contributions.
Please refer also to our Build Verification Guidelines for complete smoke testing guides.
In order to streamline the review of the contribution we ask you follow these guidelines and ask you to double check the following:
For all changes:
For documentation related changes:
Have you ensured that format looks appropriate for the output in which it is rendered by building and verifying the site-book? If not then run the following commands and the verify changes via
site-book/target/site/index.html:Note:
Please ensure that once the PR is submitted, you check travis-ci for build issues and submit an update to your PR as soon as possible.
It is also recommended that travis-ci is set up for your personal repository such that your branches are built there before submitting a pull request.