package com.tinkerpop.gremlin.structure;

import com.tinkerpop.gremlin.process.graph.VertexPropertyTraversal;
import com.tinkerpop.gremlin.structure.util.EmptyVertexProperty;

import java.util.Iterator;

/**
 * A {@code VertexProperty} is similar to a {@link Property} in that it denotes a key/value pair associated with an
 * {@link Vertex}, however it is different in the sense that it also represents an entity that it is an {@link Element}
 * that can have properties of its own.
 * <br/>
 * A property is much like a Java8 {@link java.util.Optional} in that a property can be not present (i.e. empty).
 * The key of a property is always a String and the value of a property is an arbitrary Java object.
 * Each underlying graph engine will typically have constraints on what Java objects are allowed to be used as values.
 *
 * @author Matthias Broecheler (me@matthiasb.com)
 * @author Marko A. Rodriguez (http://markorodriguez.com)
 * @author Stephen Mallette (http://stephen.genoprime.com)
 */
public interface VertexProperty<V> extends Property<V>, Element, VertexPropertyTraversal {

    public static final String DEFAULT_LABEL = "vertexProperty";

    @Override
    public Vertex element();

    @Override
    public default Graph graph() {
        return this.element().graph();
    }

    @Override
    public default String label() {
        return this.key();
    }

    public static <V> VertexProperty<V> empty() {
        return EmptyVertexProperty.instance();
    }

    @Override
    public VertexProperty.Iterators iterators();

    public interface Iterators extends Element.Iterators {

        @Override
        public <U> Iterator<Property<U>> propertyIterator(final String... propertyKeys);

        @Override
        public <U> Iterator<Property<U>> hiddenPropertyIterator(final String... propertyKeys);
    }

    /**
     * Common exceptions to use with a property.
     */
    public static class Exceptions {
        public static UnsupportedOperationException userSuppliedIdsNotSupported() {
            return new UnsupportedOperationException("VertexProperty does not support user supplied identifiers");
        }

        public static UnsupportedOperationException userSuppliedIdsOfThisTypeNotSupported() {
            return new UnsupportedOperationException("VertexProperty does not support user supplied identifiers of this type");
        }

        public static UnsupportedOperationException multiPropertiesNotSupported() {
            return new UnsupportedOperationException("Multiple properties on a vertex is not supported");
        }

        public static UnsupportedOperationException metaPropertiesNotSupported() {
            return new UnsupportedOperationException("Properties on a vertex property is not supported");
        }
    }
}

@@ -1152,16 +1152,102 @@
 erty%22;%0A%0A
+    /**%0A     * Gets the %7B@link Vertex%7D that owns this %7B@code VertexProperty%7D.%0A     */%0A
     @Ove
@@ -1278,24 +1278,61 @@
 element();%0A%0A
+    /**%0A     * %7B@inheritDoc%7D%0A     */%0A
     @Overrid
@@ -1406,32 +1406,69 @@
 graph();%0A    %7D%0A%0A
+    /**%0A     * %7B@inheritDoc%7D%0A     */%0A
     @Override%0A  
@@ -1531,24 +1531,91 @@
 y();%0A    %7D%0A%0A
+    /**%0A     * Constructs an empty %7B@code VertexProperty%7D.%0A     */%0A
     public s
@@ -1714,67 +1714,338 @@
     
-@Override%0A    public VertexProperty.Iterators iterators();%0A
+/**%0A     * Gets the %7B@link VertexProperty.Iterators%7D set.%0A     *%0A     * %7B@inheritDoc%7D%0A     */%0A    @Override%0A    public VertexProperty.Iterators iterators();%0A%0A    /**%0A     * An interface that provides access to iterators over properties, without constructing a%0A     * %7B@link com.tinkerpop.gremlin.process.Traversal%7D object.%0A     */
 %0A   
@@ -2100,16 +2100,64 @@
 ators %7B%0A
+        /**%0A         * %7B@inheritDoc%7D%0A         */
 %0A       
@@ -2253,24 +2253,73 @@
 ertyKeys);%0A%0A
+        /**%0A         * %7B@inheritDoc%7D%0A         */%0A
         @Ove

Improve javadoc.