Martin Häusler created TINKERPOP-2916:
-----------------------------------------
Summary: Documentation of the TinkerPop standard for providers
Key: TINKERPOP-2916
URL: https://issues.apache.org/jira/browse/TINKERPOP-2916
Project: TinkerPop
Issue Type: New Feature
Components: language
Affects Versions: 3.6.2
Reporter: Martin Häusler
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)
