You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@metron.apache.org by JonZeolla <gi...@git.apache.org> on 2017/11/08 15:25:05 UTC
[GitHub] metron pull request #836: DO NOT MERGE METRON-1308: Fix Metron Documentation
GitHub user JonZeolla opened a pull request:
https://github.com/apache/metron/pull/836
DO NOT MERGE METRON-1308: Fix Metron Documentation
## 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](https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=61332235) for the complete guide to follow for contributions.
Please refer also to our [Build Verification Guidelines](https://cwiki.apache.org/confluence/display/METRON/Verifying+Builds?show-miniview) 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:
- [X] Is there a JIRA ticket associated with this PR? If not one needs to be created at [Metron Jira](https://issues.apache.org/jira/browse/METRON/?selectedTab=com.atlassian.jira.jira-projects-plugin:summary-panel).
- [X] Does your PR title start with METRON-XXXX where XXXX is the JIRA number you are trying to resolve? Pay particular attention to the hyphen "-" character.
- [X] Has your PR been rebased against the latest commit within the target branch (typically master)?
### For documentation related changes:
- [X] 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`:
```
cd site-book
mvn site
```
#### 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](https://travis-ci.org) is set up for your personal repository such that your branches are built there before submitting a pull request.
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/JonZeolla/metron METRON-1308
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/metron/pull/836.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #836
----
commit 3f55bc61a15e9a1406af220181f7e022e593e19d
Author: Jon Zeolla <ze...@gmail.com>
Date: 2017-11-08T15:20:23Z
METRON-1308
commit 89d12b46dcf75fc514c56f8fa103e65ee044f504
Author: Jon Zeolla <ze...@gmail.com>
Date: 2017-11-08T15:20:33Z
Merge branch 'master' of https://github.com/apache/metron into METRON-1308
commit 6e4b2f50ed3ab0c69095b144a3c1b9f89ac92c0c
Author: Jon Zeolla <ze...@gmail.com>
Date: 2017-11-08T15:21:44Z
METRON-1308
----
---
[GitHub] metron pull request #836: DO NOT MERGE METRON-1308: Fix Metron Documentation
Posted by cestella <gi...@git.apache.org>.
Github user cestella commented on a diff in the pull request:
https://github.com/apache/metron/pull/836#discussion_r149704557
--- Diff: metron-stellar/stellar-common/README.md ---
@@ -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
--- End diff --
? implies it may be included or not, like regex
---
[GitHub] metron issue #836: DO NOT MERGE METRON-1308: Fix Metron Documentation
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on the issue:
https://github.com/apache/metron/pull/836
I just took a stab at an update, @cestella can you take a look when you get a second
---
[GitHub] metron issue #836: METRON-1308: Fix Metron Documentation
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on the issue:
https://github.com/apache/metron/pull/836
Since we have a release coming up, I won't have time to do any additional documentation review past what I've already done. @cestella have you had a chance to review?
---
[GitHub] metron pull request #836: DO NOT MERGE METRON-1308: Fix Metron Documentation
Posted by cestella <gi...@git.apache.org>.
Github user cestella commented on a diff in the pull request:
https://github.com/apache/metron/pull/836#discussion_r149703967
--- Diff: metron-stellar/stellar-common/README.md ---
@@ -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
--- End diff --
It's a repetition symbol, so it implies you can have any number of values.
---
[GitHub] metron issue #836: DO NOT MERGE METRON-1308: Fix Metron Documentation
Posted by cestella <gi...@git.apache.org>.
Github user cestella commented on the issue:
https://github.com/apache/metron/pull/836
So, answering your questions en-masse we use the following similar to how they exist in regex:
* `*` - `0` or `n` instances
* `?` - `0` or `1` instance
* `+` - `1` or `n` instances
In retrospect, this may not be as obvious as it seemed at the time. Think we need a key that indicates this? ;)
---
[GitHub] metron pull request #836: DO NOT MERGE METRON-1308: Fix Metron Documentation
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on a diff in the pull request:
https://github.com/apache/metron/pull/836#discussion_r149701286
--- Diff: metron-stellar/stellar-common/README.md ---
@@ -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.
* 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.
--- End diff --
Why does this have an \*?
---
[GitHub] metron issue #836: METRON-1308: Fix Metron Documentation
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on the issue:
https://github.com/apache/metron/pull/836
@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.
---
[GitHub] metron pull request #836: METRON-1308: Fix Metron Documentation
Posted by asfgit <gi...@git.apache.org>.
Github user asfgit closed the pull request at:
https://github.com/apache/metron/pull/836
---
[GitHub] metron pull request #836: DO NOT MERGE METRON-1308: Fix Metron Documentation
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on a diff in the pull request:
https://github.com/apache/metron/pull/836#discussion_r149701209
--- Diff: metron-stellar/stellar-common/README.md ---
@@ -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
--- End diff --
Why does this have a \??
---
[GitHub] metron pull request #836: DO NOT MERGE METRON-1308: Fix Metron Documentation
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on a diff in the pull request:
https://github.com/apache/metron/pull/836#discussion_r149701086
--- Diff: metron-stellar/stellar-common/README.md ---
@@ -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
--- End diff --
Why does this have an \*?
---
[GitHub] metron issue #836: METRON-1308: Fix Metron Documentation
Posted by nickwallen <gi...@git.apache.org>.
Github user nickwallen commented on the issue:
https://github.com/apache/metron/pull/836
+1 I like this @JonZeolla. This reads more clearly IMHO.
---
[GitHub] metron issue #836: METRON-1308: Fix Metron Documentation
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on the issue:
https://github.com/apache/metron/pull/836
Merged master, ran tests successfully, built site-books and did some clicking around. Going to merge.
---
[GitHub] metron pull request #836: DO NOT MERGE METRON-1308: Fix Metron Documentation
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on a diff in the pull request:
https://github.com/apache/metron/pull/836#discussion_r149701260
--- Diff: metron-stellar/stellar-common/README.md ---
@@ -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.
--- End diff --
Why does this have an \*?
---
[GitHub] metron issue #836: DO NOT MERGE METRON-1308: Fix Metron Documentation
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on the issue:
https://github.com/apache/metron/pull/836
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](https://metron.apache.org/current-book/metron-stellar/stellar-common/index.html) and [here](https://github.com/apache/metron/blob/master/metron-stellar/stellar-common/README.md)) which we've seen bite us numerous times in the past in our docs.
---
[GitHub] metron pull request #836: DO NOT MERGE METRON-1308: Fix Metron Documentation
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on a diff in the pull request:
https://github.com/apache/metron/pull/836#discussion_r149706098
--- Diff: metron-stellar/stellar-common/README.md ---
@@ -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
--- End diff --
Okay, I get your intent now. It was being suppressed before because it wasn't escaped, I will try to make it more obvious.
---
[GitHub] metron pull request #836: DO NOT MERGE METRON-1308: Fix Metron Documentation
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on a diff in the pull request:
https://github.com/apache/metron/pull/836#discussion_r149701164
--- Diff: metron-stellar/stellar-common/README.md ---
@@ -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
--- End diff --
Why does this have a \??
---
[GitHub] metron pull request #836: DO NOT MERGE METRON-1308: Fix Metron Documentation
Posted by JonZeolla <gi...@git.apache.org>.
Github user JonZeolla commented on a diff in the pull request:
https://github.com/apache/metron/pull/836#discussion_r149706457
--- Diff: metron-stellar/stellar-common/README.md ---
@@ -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
--- End diff --
Gotcha, okay. I think I would prefer something like (optional), what do you think?
---