span operations API (#29)

* span operations API

* fixed TBD on span

* fixed a link

* addressed Bogdan's feedback

* fixed optionality of attributes

* Update tracing-api.md

work_in_progress/specification/README.md

@@ -139,48 +139,7 @@ Both injection and extraction rely on an extensible **format** parameter that di
 
 ### `Span`
 
-With the exception of the method to retrieve the `Span`'s `SpanContext`, none of the below may be called after the `Span` is finished.
-
-#### Retrieve the `Span`s `SpanContext`
-
-There should be no parameters.
-
-**Returns** the `SpanContext` for the given `Span`. The returned value may be used even after the `Span` is finished.
-
-#### Overwrite the operation name
-
-Required parameters
-
-- The new **operation name**, which supersedes whatever was passed in when the `Span` was started
-
-#### Finish the `Span`
-
-Optional parameters
-
-- An explicit **finish timestamp** for the `Span`; if omitted, the current walltime is used implicitly.
-
-With the exception of the method to retrieve a `Span`'s `SpanContext`, no method may be called on a `Span` instance after it's finished.
-
-#### Set a `Span` tag
-
-Required parameters
-
-- The tag key, which must be a string
-- The tag value, which must be either a string, a boolean value, or a numeric type
-
-Note that the OpenTracing project documents certain **["standard tags"](./semantic_conventions.md#span-tags-table)** that have prescribed semantic meanings.
-
-#### Log structured data
-
-Required parameters
-
-- One or more key:value pairs, where the keys must be strings and the values may have any type at all. Some OpenTracing implementations may handle more (or more of) certain log values than others.
-
-Optional parameters
-
-- An explicit timestamp. If specified, it must fall between the local start and finish time for the span.
-
-Note that the OpenTracing project documents certain **["standard log keys"](./semantic_conventions.md#log-fields-table)** which have prescribed semantic meanings.
+... moved to [specs](../../specification/tracing-api.md)...
 
 #### Set a **baggage** item
 

work_in_progress/specification/trace/README.md

@@ -1,6 +1,4 @@
 # OpenCensus Library Trace Package
-This documentation serves to document the "look and feel" of the open source tags package. It 
-describes the key types and the overall behavior.
 
 ## Main APIs
 * [Span](Span.md)

work_in_progress/specification/trace/Span.md

@@ -1,4 +1,5 @@
 # Span
+ 
 
 ... parts of this document moved to [terminology.md](../terminology.md) ...
 
@@ -40,12 +41,6 @@ Span is attached (immutable Context):
 * When attach/detach an already created Span the API MAY be called `WithSpan`.
 * When attach/detach at the creation time the API MAY be called `StartSpan` or `StartScopedSpan`.
 
-### What is Span lifetime?
-Span lifetime represents the process of recording the start and the end timestamps to the Span 
-object:
-* The start time is recorded when the Span is created.
-* The end time needs to be recorded when the operation is ended.
-
 ### Why support Spans that are not attached to the Context?
 * Allow users to use the OpenCensus library without using a Context.
 * Allow users to have more control for the lifetime of the Span.