From ad1c6e75e273299efee5914084fccf182aa23d68 Mon Sep 17 00:00:00 2001
From: Jeffrey Phillips Freeman <jeffrey.freeman@syncleus.com>
Date: Tue, 8 Nov 2016 00:28:06 -0500
Subject: [PATCH] Rearranged documenation.

Change-Id: I60c0837290cd1582f0f28cd93fba6aa49f1cf080
---
 .../adjacency.md}                             | 153 +++---------------
 docs/annotations/overview.md                  |   7 +
 docs/annotations/property.md                  | 110 +++++++++++++
 docs/comparing_the_alternatives.md            |  24 +--
 mkdocs.yml                                    |  10 +-
 5 files changed, 155 insertions(+), 149 deletions(-)
 rename docs/{core_annotations.md => annotations/adjacency.md} (68%)
 create mode 100644 docs/annotations/overview.md
 create mode 100644 docs/annotations/property.md

diff --git a/docs/core_annotations.md b/docs/annotations/adjacency.md
similarity index 68%
rename from docs/core_annotations.md
rename to docs/annotations/adjacency.md
index 08eca9af..e1abe1c4 100644
--- a/docs/core_annotations.md
+++ b/docs/annotations/adjacency.md
@@ -1,120 +1,3 @@
-[TOC]
-
-The Ferma schema is defined by a collection of interfaces and classes written by the user. Each method will interact with the underlying graph to either modify the graph in some way, or to retrieve an element or property from the graph. There are two techniques for defining how these methods behave. Either you can explicitly implement the method, or you can leave the method as abstract and annotate the method in order to allow Ferma to implement the method for you. Here we will define the annotations available to you and how they work, along with a few examples.
-
-The behavior of an annotated method is dictated not only by the annotation applied to it but also the method's signature. Therefore an annotated method will behave differently if it's return type, arguments, or even if the method name were to change. It is important to note that when a method is explicitly defined (doesnt use an annotation) then the method signature can be anything.
-
-Method names that are annotated must have one of the following prefixes: add, get, remove, set, is, can.
-
-Below specifies that annotations that can be used when defining a Frame's interface. By specifying the method argument and return types, the underlying graph is constrained to the interface specification.
-
-## Property annotation
-
-Valid on frames: Edge and Vertex
-
-Allowed prefixes: `get`, `is`, `can`, `set`, `remove`
-
-Annotation arguments:
-
-`value` - The name of the property
-
-The following would bind the method it is used on to the property named `foo`:
-
-```java
-@Property("foo")
-//Method declared here
-```
-
-### get prefix
-
-Valid method signatures: `()`
-
-#### ()
-
-Valid return types: *Any Object*
-
-Get the property value of an element. Used when property is not a boolean value.
-
-example:
-
-```java
-@Property("Foo")
-Bar getFoobar()
-```
-
-```java
-@Property("Foo")
-<E extends Bar> E getFoobar()
-```
-
-```java
-@Property("Foo")
-<E> E getFoobar()
-```
-
-### is prefix
-
-Valid method signatures: `()`
-
-#### ()
-
-Valid return types: `boolean`
-
-Get the property value of an element. Used when property is a boolean value.
-
-example:
-
-```java
-@Property("Foobared")
-boolean isFoobared()
-```
-
-### set prefix
-
-Valid method signatures: `(Object)`
-
-#### (Object)
-
-Valid return types: `void`
-
-Set the property value of an element. The argument can be any class accepted by the underlying graph.
-
-example:
-
-```java
-@Property("Foo")
-void setFoobar(Bar foobar)
-```
-
-```java
-@Property("Foo")
-<E extends Bar> void setFoobar(E foobar)
-```
-
-```java
-@Property("Foo")
-<E extends VectorFrame> void setFoobar(E foobar)
-```
-
-### remove prefix
-
-Valid method signatures: `()`
-
-#### ()
-
-Valid return types: `void`
-
-Remove the property of an element.
-
-example:
-
-```java
-@Property("Foo")
-void removeFoobar()
-```
-
-## Adjacency annotation
-
 Valid on frames: Vertex
 
 Allowed prefixes: `add`, `get`, `remove`, `set`
@@ -125,13 +8,15 @@ Annotation arguments:
 
 `direction` - The direction for the edge which creates the adjacency. It can be assigned any of the values from @org.apache.tinkerpop.gremlin.structure.Direction@.
 
-### add prefix
+
+## add prefix
 
 Valid method signatures: `()`, `(<Any Vertex Frame>)`, `(ClassInitializer)`, `(ClassInitializer, ClassInitializer)`
 
 Adds a node as an adjacency to the current node, and the returns the newly connected node.
 
-#### ()
+
+### ()
 
 Valid return types: `Object` or `VertexFrame`
 
@@ -144,7 +29,8 @@ example:
 VertexFrame addFoobar()
 ```
 
-#### (&lt;Any Vertex Frame&gt;)
+
+### (&lt;Any Vertex Frame&gt;)
 
 Valid return types: *Any Vertex Frame*
 
@@ -167,7 +53,8 @@ Bar addFoobar(Bar existingVertex)
 <E extends VertexFrame> E addFoobar(E existingVertex)
 ```
 
-#### (ClassInitializer)
+
+### (ClassInitializer)
 
 Valid return types: *Any Vertex Frame*
 
@@ -190,7 +77,8 @@ Bar addFoobar(ClassInitializer<? extends Bar> vertexInitializer)
 <E extends VertexFrame> E addFoobar(ClassInitializer<? extends E> vertexInitializer)
 ```
 
-#### (ClassInitializer, ClassInitializer)
+
+### (ClassInitializer, ClassInitializer)
 
 Valid return types: *Any Vertex Frame*
 
@@ -216,13 +104,15 @@ Bar addFoobar(ClassInitializer<? extends Bar> vertexInitializer,
                                     ClassInitializer<?> edgeInitializer)
 ```
 
-### get prefix
+
+## get prefix
 
 Valid method signatures: `()`, `(Class)`
 
 Get's one or more adjacent vertex from the graph.
 
-#### ()
+
+### ()
 
 Valid return types: *Any Vertex Frame* or `Object` or `VertexFrame` or `Iterator`
 
@@ -262,7 +152,8 @@ Iterator<Bar> getFoobar()
 <E extends VertexFrame> Iterator<E> getFoobar()
 ```
 
-#### (Class)
+
+### (Class)
 
 Valid return types: *Any Vertex Frame* or `Object` or `VertexFrame` or `Iterator`
 
@@ -302,13 +193,15 @@ Iterator<Bar> getFoobar(Class<? extends Bar> filter)
 <E extends VertexFrame> Iterator<E> getFoobar(Class<? extends E> filter)
 ```
 
-### remove prefix
+
+## remove prefix
 
 Valid method signatures: `(<Any Vertex Frame>)`
 
 Removes any edges which cause an adjacency.
 
-#### (&lt;Any Vertex Frame&gt;)
+
+### (&lt;Any Vertex Frame&gt;)
 
 Valid return types: `void`
 
@@ -331,13 +224,15 @@ void removeFoobar(Bar vertex)
 <E extends VertexFrame> void removeFoobar(E vertex)
 ```
 
-### set prefix
+
+## set prefix
 
 Valid method signatures: `(Iterator)`
 
 Creates new edges connected to several vertex.
 
-#### (Iterator)
+
+### (Iterator)
 
 Valid return types: `void`
 
diff --git a/docs/annotations/overview.md b/docs/annotations/overview.md
new file mode 100644
index 00000000..ddb5d6a5
--- /dev/null
+++ b/docs/annotations/overview.md
@@ -0,0 +1,7 @@
+The Ferma schema is defined by a collection of interfaces and classes written by the user. Each method will interact with the underlying graph to either modify the graph in some way, or to retrieve an element or property from the graph. There are two techniques for defining how these methods behave. Either you can explicitly implement the method, or you can leave the method as abstract and annotate the method in order to allow Ferma to implement the method for you. Here we will define the annotations available to you and how they work, along with a few examples.
+
+The behavior of an annotated method is dictated not only by the annotation applied to it but also the method's signature. Therefore an annotated method will behave differently if it's return type, arguments, or even if the method name were to change. It is important to note that when a method is explicitly defined (doesnt use an annotation) then the method signature can be anything.
+
+Method names that are annotated must have one of the following prefixes: add, get, remove, set, is, can.
+
+Below specifies that annotations that can be used when defining a Frame's interface. By specifying the method argument and return types, the underlying graph is constrained to the interface specification.
diff --git a/docs/annotations/property.md b/docs/annotations/property.md
new file mode 100644
index 00000000..ce0b7a51
--- /dev/null
+++ b/docs/annotations/property.md
@@ -0,0 +1,110 @@
+Valid on frames: Edge and Vertex
+
+Allowed prefixes: `get`, `is`, `can`, `set`, `remove`
+
+Annotation arguments:
+
+`value` - The name of the property
+
+The following would bind the method it is used on to the property named `foo`:
+
+```java
+@Property("foo")
+//Method declared here
+```
+
+
+## get prefix
+
+Valid method signatures: `()`
+
+
+### ()
+
+Valid return types: *Any Object*
+
+Get the property value of an element. Used when property is not a boolean value.
+
+example:
+
+```java
+@Property("Foo")
+Bar getFoobar()
+```
+
+```java
+@Property("Foo")
+<E extends Bar> E getFoobar()
+```
+
+```java
+@Property("Foo")
+<E> E getFoobar()
+```
+
+
+## is prefix
+
+Valid method signatures: `()`
+
+
+### ()
+
+Valid return types: `boolean`
+
+Get the property value of an element. Used when property is a boolean value.
+
+example:
+
+```java
+@Property("Foobared")
+boolean isFoobared()
+```
+
+
+## set prefix
+
+Valid method signatures: `(Object)`
+
+
+### (Object)
+
+Valid return types: `void`
+
+Set the property value of an element. The argument can be any class accepted by the underlying graph.
+
+example:
+
+```java
+@Property("Foo")
+void setFoobar(Bar foobar)
+```
+
+```java
+@Property("Foo")
+<E extends Bar> void setFoobar(E foobar)
+```
+
+```java
+@Property("Foo")
+<E extends VectorFrame> void setFoobar(E foobar)
+```
+
+
+## remove prefix
+
+Valid method signatures: `()`
+
+
+### ()
+
+Valid return types: `void`
+
+Remove the property of an element.
+
+example:
+
+```java
+@Property("Foo")
+void removeFoobar()
+```
diff --git a/docs/comparing_the_alternatives.md b/docs/comparing_the_alternatives.md
index 164a3b9c..8dabb3c7 100644
--- a/docs/comparing_the_alternatives.md
+++ b/docs/comparing_the_alternatives.md
@@ -1,7 +1,6 @@
 There are several OGM/ORM options out there. For the purposes of this document we will focus only on those that have a stable release, or are close to a stable release. At the time of this writing those are: Tinkerpop Framed and Totorom.
 
-Benchmarks
-==========
+## Benchmarks
 
 We maintain an informal project for benchmarking Ferma against other OGM available, you can find the [source here](https://github.com/Syncleus/Ferma-benchmark). However below is a matrix breakdown of the results. Instead of showing raw execution time we show the ratio of each OGM compared to Ferma. Therefore if the table lists 1x then it means the framework has the same execution time as Ferma, if it lists 2x then it took twice as long to execute, and if it indicates 0.5x then it took half the time to execute. Obviously any value less than 1x indicates the OGM out performed Ferma and any value greater than 1x indicates Ferma had the superior performance tiimes.
 
@@ -15,8 +14,7 @@ We maintain an informal project for benchmarking Ferma against other OGM availab
 
 As can be seen Ferma out performs all the alternative solutions considerably by several orders of magnitude. While results do vary slightly from system to system these results are pretty close to typical. Go ahead, check out the benchmark program and run it for yourself!
 
-Feature Breakdown
-=================
+## Feature Breakdown
 
 Despite the superior performance of Ferma it also supports all the features provided by the alternatives out there, not to mention several novel features. The following gives a quick breakdown of the features of the various frameworks. We also include a bit later in the document some Ferma examples showing the various features in action. All of the examples below use the domain model [found here](Ferma:Domain_Example).
 
@@ -34,8 +32,7 @@ Despite the superior performance of Ferma it also supports all the features prov
 
 \* While Peapod does support querying for all instances of a type, and its subtypes, it does not support a mechanism to query for a specific type while excluding subtypes.
 
-Type information encoded into graph
------------------------------------
+### Type information encoded into graph
 
 ```java
 Set<Class<?>> types = new HashSet<Class<?>>(Arrays.asList(new Class<?>[]{Person.class}));
@@ -50,8 +47,7 @@ String encodedClassName = person.getProperty(PolymorphicTypeResolver.TYPE_RESOLU
 assert(personClassName.equals(encodedClassName));
 ```
 
-Framing instantiated by type hierarchy
---------------------------------------
+### Framing instantiated by type hierarchy
 
 ```java
 Set<Class<?>> types = new HashSet<Class<?>>(Arrays.asList(new Class<?>[]{Person.class,
@@ -66,8 +62,7 @@ Person programmer = fg.v().next(Person.class);
 assert(programmer instanceof Programmer);
 ```
 
-Element queried by type hierarchy
----------------------------------
+### Element queried by type hierarchy
 
 ```java
 Set<Class<?>> types = new HashSet<Class<?>>(Arrays.asList(new Class<?>[]{Person.class,
@@ -84,8 +79,7 @@ assert(fg.v().has(Person.class).count() == 2);
 assert(fg.v().has(Programmer.class).count() == 1);
 ```
 
-Turning off type resolution per call
-------------------------------------
+### Turning off type resolution per call
 
 ```java
 Set<Class<?>> types = new HashSet<Class<?>>(Arrays.asList(new Class<?>[]{Person.class,
@@ -101,8 +95,7 @@ assert(fg.v().next(Person.class) instanceof Programmer);
 assert(!(fg.v().nextExplicit(Person.class) instanceof Programmer));
 ```
 
-Changing type encoded in the graph
-----------------------------------
+### Changing type encoded in the graph
 
 ```java
 Set<Class<?>> types = new HashSet<Class<?>>(Arrays.asList(new Class<?>[]{Person.class,
@@ -125,8 +118,7 @@ assert(person instanceof Person);
 assert(!(person instanceof Programmer));
 ```
 
-Customizing how types are encoded
----------------------------------
+### Customizing how types are encoded
 
 ```java
 Set<Class<?>> types = new HashSet<Class<?>>(Arrays.asList(new Class<?>[]{Person.class}));
diff --git a/mkdocs.yml b/mkdocs.yml
index fa455535..474dc090 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -5,10 +5,13 @@ repo_url: 'https://github.com/Syncleus/Ferma'
 site_dir: 'target/mkdocs'
 pages:
     - Home: index.md
-    - Comparing the Alternatives: comparing_the_alternatives.md
-    - Core Annotations: core_annotations.md
     - Getting Started: getting_started.md
+    - Comparing the Alternatives: comparing_the_alternatives.md
     - Glossary: glossary.md
+    - Core Annotations:
+        - Overview: annotations/overview.md
+        - '@Propery': annotations/property.md
+        - '@adjacency': annotations/adjacency.md
 extra:
   version: '3.0.1'
   logo: 'images/ferma-logo.svg'
@@ -18,8 +21,7 @@ extra:
     primary: 'blue'
     accent: 'deep orange'
   author:
-    github: 'freemo'
-    twitter: 'DebeoMorium'
+    github: 'Syncleus'
 
 markdown_extensions:
   - codehilite(css_class=code)
-- 
GitLab