[jira] [Commented] (TINKERPOP-2392) Improve module level documentation for GLVs

["ASF GitHub Bot (Jira)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/TINKERPOP-2392?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17189285#comment-17189285 ] 

ASF GitHub Bot commented on TINKERPOP-2392:
-------------------------------------------

jorgebay commented on a change in pull request #1321:
URL: https://github.com/apache/tinkerpop/pull/1321#discussion_r482083923



##########
File path: gremlin-python/src/main/jython/README.rst
##########
@@ -54,8 +54,65 @@ remote graph:
     >>> g.V().both().name.toList()
     [lop, vadas, josh, marko, marko, josh, peter, ripple, lop, marko, josh, lop]
 
-Please see the `reference documentation <http://tinkerpop.apache.org/docs/current/reference/#gremlin-python>`_
-at Apache TinkerPop for more information on usage.
+-----------------
+Sample Traversals
+-----------------
+
+The Gremlin language allows users to write highly expressive graph traversals and has a broad list of functions that
+cover a wide body of features. The `Reference Documentation <https://tinkerpop.apache.org/docs/current/reference/#graph-traversal-steps>`_
+describes these functions and other aspects of the TinkerPop ecosystem including some specifics on
+`Gremlin in Python <https://tinkerpop.apache.org/docs/current/reference/#gremlin-python>`_ itself. Most of the
+examples found in the documentation use Groovy language syntax in the
+`Gremlin Console <https://tinkerpop.apache.org/docs/current/tutorials/the-gremlin-console/>`_.
+For the most part, these examples should generally translate to Python with
+`some modification <https://tinkerpop.apache.org/docs/current/reference/#gremlin-python-differences>`_. Given the
+strong correspondence between canonical Gremlin in Java and its variants like Python, there is a limited amount of
+Python-specific documentation and examples. This strong correspondence among variants ensures that the general
+Gremlin reference documentation is applicable to all variants and that users moving between development languages can
+easily adopt the Gremlin variant for that language.
+
+Create Vertex
+^^^^^^^^^^^^^
+
+.. code:: python
+
+    from gremlin_python.process.traversal import T
+    from gremlin_python.process.traversal import Cardinality
+
+    id = T.id
+    single = Cardinality.single
+
+    def create_vertex(self, vid, vlabel):
+        g.addV(vlabel).property(id, vid). \
+          property(single, 'name', 'Apache'). \
+          property('lastname', 'Tinkerpop'). \ # default database cardinality

Review comment:
       Comment block after line continuation character is not valid.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


> Improve module level documentation for GLVs
> -------------------------------------------
>
>                 Key: TINKERPOP-2392
>                 URL: https://issues.apache.org/jira/browse/TINKERPOP-2392
>             Project: TinkerPop
>          Issue Type: Improvement
>          Components: javascript
>    Affects Versions: 3.4.7
>            Reporter: James Sumners
>            Assignee: Stephen Mallette
>            Priority: Minor
>
> As an example of the general problem, the readme for the JavaScript client says:
> "Please see the [reference documentation|http://tinkerpop.apache.org/docs/current/reference/#gremlin-javascript] at Apache TinkerPop for more information."
> That reference documentation is completely written in Groovy and does not translate well to JavaScript. At the very least, there should be some documentation that describes how to translate all of the globals used across the reference documentation. For example, in [http://tinkerpop.apache.org/docs/current/reference/#valuemap-step] it is suggested that one can translate the list based values to singular values by writing:
> {code}
> g.V().valueMap().by(unfold())
> {code}
> How do I translate this for usage in the JavaScript client? I assume the `unfold()` method needs to be attached to the instance referenced by the `by()` function. How do I get that reference easily? Can I pass a parameter like `.by( () => this.unfold() )` (it certainly doesn't work)? Neither `.by("unfold()")` nor `.by("unfold")` work.
> This sort of thing is present throughout the reference documentation and is making it very difficult to get up-to-speed with the JavaScript client.



--
This message was sent by Atlassian Jira
(v8.3.4#803005)