allow to define extra docs for named steps (#113)

Author: mpollmeier

Diff for: codegen/src/main/scala/overflowdb/codegen/CodeGen.scala

@@ -458,18 +458,21 @@ class CodeGen(schema: Schema) {
             val neighbor = adjacentNode.neighbor
             val entireNodeHierarchy: Set[AbstractNodeType] = neighbor.subtypes(schema.allNodeTypes.toSet) ++ (neighbor.extendzRecursively :+ neighbor)
             entireNodeHierarchy.map { neighbor =>
-              val accessorName = {
-                if (adjacentNode.customStepName.isEmpty)
-                  s"_${camelCase(neighbor.name)}Via${edge.className.capitalize}${camelCaseCaps(direction.toString)}"
-                else adjacentNode.customStepName
-              }
+              val accessorName = adjacentNode.customStepName.getOrElse(
+                s"_${camelCase(neighbor.name)}Via${edge.className.capitalize}${camelCaseCaps(direction.toString)}"
+              )
               val cardinality = adjacentNode.cardinality
               val appendix = cardinality match {
                 case EdgeType.Cardinality.One => ".next()"
                 case EdgeType.Cardinality.ZeroOrOne => s".nextOption()"
                 case _ => ""
               }
-              s"def $accessorName: ${fullScalaType(neighbor, cardinality)} = $edgeAccessorName.collectAll[${neighbor.className}]$appendix"
+
+              s"""/** ${adjacentNode.customStepDoc.getOrElse("")}
+                 |  * Traverse to ${neighbor.name} via ${adjacentNode.viaEdge.name}.
+                 |  */
+                 |def $accessorName: ${fullScalaType(neighbor, cardinality)} =
+                 |  $edgeAccessorName.collectAll[${neighbor.className}]$appendix""".stripMargin
             }
           }.distinct.mkString("\n\n")
 
@@ -582,7 +585,7 @@ class CodeGen(schema: Schema) {
         def createNeighborInfos(neighborContexts: Seq[AjacentNodeWithInheritanceStatus], direction: Direction.Value): Seq[NeighborInfoForEdge] = {
           neighborContexts.groupBy(_.adjacentNode.viaEdge).map { case (edge, neighborContexts) =>
             val neighborInfoForNodes = neighborContexts.map { case AjacentNodeWithInheritanceStatus(adjacentNode, isInherited) =>
-              NeighborInfoForNode(adjacentNode.neighbor, edge, direction, adjacentNode.cardinality, isInherited, Option(adjacentNode.customStepName).filter(_.nonEmpty))
+              NeighborInfoForNode(adjacentNode.neighbor, edge, direction, adjacentNode.cardinality, isInherited, adjacentNode.customStepName, adjacentNode.customStepDoc)
             }
             NeighborInfoForEdge(edge, neighborInfoForNodes, nextOffsetPos)
           }.toSeq
@@ -1151,14 +1154,15 @@ class CodeGen(schema: Schema) {
 
     def generateCustomStepNameTraversals(nodeType: AbstractNodeType): String = {
       nodeType.edges
-        .filter(_.customStepName.nonEmpty)
         .sortBy(_.customStepName)
-        .map { case AdjacentNode(viaEdge, neighbor, cardinality, customStepName) =>
+        .collect { case AdjacentNode(viaEdge, neighbor, cardinality, Some(customStepName), customStepDoc) =>
           val mapOrFlatMap = cardinality match {
             case Cardinality.One => "map"
             case Cardinality.ZeroOrOne | Cardinality.List => "flatMap"
           }
-          s"""/** traverse to ${neighbor.name} via ${viaEdge.name} - this relationship was given a customStepName in the schema */
+          s"""/** ${customStepDoc.getOrElse("")}
+             |  * Traverse to ${neighbor.name} via ${viaEdge.name} - this relationship was given a customStepName in the schema.
+             |  */
              |def $customStepName: Traversal[${neighbor.className}] =
              |  traversal.$mapOrFlatMap(_.$customStepName)
              |""".stripMargin

Diff for: codegen/src/main/scala/overflowdb/schema/Schema.scala

@@ -76,9 +76,11 @@ abstract class AbstractNodeType(val name: String, val comment: Option[String], v
                  cardinalityOut: EdgeType.Cardinality = EdgeType.Cardinality.List,
                  cardinalityIn: EdgeType.Cardinality = EdgeType.Cardinality.List,
                  stepNameOut: String = "",
-                 stepNameIn: String = ""): this.type = {
-    _outEdges.add(AdjacentNode(edge, inNode, cardinalityOut, stepNameOut))
-    inNode._inEdges.add(AdjacentNode(edge, this, cardinalityIn, stepNameIn))
+                 stepNameOutDoc: String = "",
+                 stepNameIn: String = "",
+                 stepNameInDoc: String = ""): this.type = {
+    _outEdges.add(AdjacentNode(edge, inNode, cardinalityOut, stringToOption(stepNameOut), stringToOption(stepNameOutDoc)))
+    inNode._inEdges.add(AdjacentNode(edge, this, cardinalityIn, stringToOption(stepNameIn), stringToOption(stepNameInDoc)))
     this
   }
 
@@ -87,9 +89,11 @@ abstract class AbstractNodeType(val name: String, val comment: Option[String], v
                 cardinalityIn: EdgeType.Cardinality = EdgeType.Cardinality.List,
                 cardinalityOut: EdgeType.Cardinality = EdgeType.Cardinality.List,
                 stepNameIn: String = "",
-                stepNameOut: String = ""): this.type = {
-    _inEdges.add(AdjacentNode(edge, outNode, cardinalityIn, stepNameIn))
-    outNode._outEdges.add(AdjacentNode(edge, this, cardinalityOut, stepNameOut))
+                stepNameInDoc: String = "",
+                stepNameOut: String = "",
+                stepNameOutDoc: String = ""): this.type = {
+    _inEdges.add(AdjacentNode(edge, outNode, cardinalityIn, stringToOption(stepNameIn), stringToOption(stepNameInDoc)))
+    outNode._outEdges.add(AdjacentNode(edge, this, cardinalityOut, stringToOption(stepNameOut), stringToOption(stepNameOutDoc)))
     this
   }
 
@@ -141,7 +145,9 @@ class NodeBaseType(name: String, comment: Option[String], schemaInfo: SchemaInfo
   override def toString = s"NodeBaseType($name)"
 }
 
-case class AdjacentNode(viaEdge: EdgeType, neighbor: AbstractNodeType, cardinality: EdgeType.Cardinality, customStepName: String)
+case class AdjacentNode(viaEdge: EdgeType, neighbor: AbstractNodeType, cardinality: EdgeType.Cardinality,
+                        customStepName: Option[String] = None,
+                        customStepDoc: Option[String] = None)
 
 case class ContainedNode(nodeType: AbstractNodeType, localName: String, cardinality: Property.Cardinality)
 
@@ -253,13 +259,14 @@ case class NeighborInfoForNode(
   direction: Direction.Value,
   cardinality: EdgeType.Cardinality,
   isInherited: Boolean,
-  customStepName: Option[String] = None) {
+  customStepName: Option[String] = None,
+  customStepDoc: Option[String] = None) {
 
   /** handling some accidental complexity within the schema: if a relationship is defined on a base node and
    * separately on a concrete node, with different cardinalities, we need to use the highest cardinality  */
   lazy val consolidatedCardinality: EdgeType.Cardinality = {
     val inheritedCardinalities = neighborNode.extendzRecursively.flatMap(_.inEdges).collect {
-      case AdjacentNode(viaEdge, neighbor, cardinality, _)
+      case AdjacentNode(viaEdge, neighbor, cardinality, _, _)
         if viaEdge == edge && neighbor == neighborNode => cardinality
     }
     val allCardinalities = cardinality +: inheritedCardinalities

Diff for: integration-tests/schemas/src/main/scala/TestSchema02.scala

@@ -40,6 +40,7 @@ class TestSchema02 extends TestSchema {
     cardinalityOut = EdgeType.Cardinality.List,
     cardinalityIn = EdgeType.Cardinality.ZeroOrOne,
     stepNameOut = "customStepName1",
+    stepNameOutDoc = "custom step name 1 documentation",
     stepNameIn = "customStepName1Inverse")
 
   node2.addOutEdge(
@@ -48,5 +49,6 @@ class TestSchema02 extends TestSchema {
     cardinalityOut = EdgeType.Cardinality.One,
     cardinalityIn = EdgeType.Cardinality.One,
     stepNameOut = "customStepName2",
+    stepNameOutDoc = "custom step name 2 documentation",
     stepNameIn = "customStepName2Inverse")
 }