[
https://issues.apache.org/jira/browse/TINKERPOP-2916?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17708001#comment-17708001
]
Stephen Mallette commented on TINKERPOP-2916:
---------------------------------------------
More documentation is always a good goal. We've tried to start coming up with
better provider documentation around Gremlin semantics here:
https://tinkerpop.apache.org/docs/current/dev/provider/#gremlin-semantics
but you can see it is incomplete and progress is slow. I'm not even wholly
convinced we have the structure for that right in documenting steps so it may
yet require more change to get that right. I tend to think it better to
document Gremlin the language rather than the Java implementation for
describing how steps are meant to work and then enforcing that with the gherkin
test suite.
As for this issue here, I'm not sure it's good as an issue for JIRA because we
try to keep the issues created here actionable and this one is really big.
Realistically, I think the docs will mostly get improved as part of smaller
bodies of work that involve test improvement, fixes to Gremlin inconsistencies
and bugs and other similar work on code.
That's not to say we wouldn't like someone to just offer documentation pull
requests that could help make improvements of the size scoped here though :)
> Documentation of the TinkerPop standard for providers
> -----------------------------------------------------
>
> Key: TINKERPOP-2916
> URL: https://issues.apache.org/jira/browse/TINKERPOP-2916
> Project: TinkerPop
> Issue Type: Improvement
> Components: language
> Affects Versions: 3.6.2
> Reporter: Martin Häusler
> Priority: Major
>
> As a TinkerPop graph developer, I am often faced with the "internals" of
> TinkerPop (classes such as {{TraversalRing}} and step classes such as
> {{CollectingBarrierStep}} which do not appear in the user-level
> documentation) and I have to do quite a lot of code reading to understand the
> concepts.
> It would be super helpful to have (at least) class level documentation on how
> the internal concepts work. Method level documentation would also be nice;
> for example I only recently fully understood how the {{starts}} field of a
> traversal really works.
> Alternatively / additionally, a documentation page for TinkerPop providers
> which explains the non-user-facing (internal) aspects would be nice to have.
> I know about this page:
> https://tinkerpop.apache.org/docs/current/dev/provider/
> ... and it's good, but it again skips on many internals (for example, it
> should explain that there are so many different implementations of the
> Traverser interface because each step has requirements and the requirements
> of the traversal guide the selection of the traverser class, which have
> varying capabilities). I've been piecing together this knowledge myself over
> time, but that's not only tedious, but also somewhat dangerous because I may
> have got it wrong, or maybe I'm missing some key information. In other words,
> I feel like we need an RFC-style "standard" which transcends the code itself.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
