Documentation improvements

packages/apm/src/hubextensions.ts

@@ -20,9 +20,9 @@ function traceHeaders(this: Hub): { [key: string]: string } {
 }
 
 /**
- * This functions starts a span. If there is already a `Span` on the Scope,
+ * This function starts a span. If there is already a `Span` on the Scope,
  * the created Span with the SpanContext will have a reference to it and become it's child.
- * Otherwise it'll crete a new `Span`.
+ * Otherwise it'll create a new `Span`.
  *
  * @param context Properties with which the span should be created
  */

packages/apm/src/span.ts

@@ -77,7 +77,7 @@ export class Span implements SpanInterface, SpanContext {
   public spanRecorder?: SpanRecorder;
 
   /**
-   * You should never call the custructor manually, always use `hub.startSpan()`.
+   * You should never call the constructor manually, always use `hub.startSpan()`.
    * @internal
    * @hideconstructor
    * @hidden

packages/apm/src/transaction.ts

@@ -46,7 +46,8 @@ export class Transaction extends SpanClass {
   private readonly _trimEnd?: boolean;
 
   /**
-   * This constructor should never be called manually. Those instrumenting tracing should use `Stentry.startTransaction()`, and internal methods should use `hub.startSpan()`.
+   * This constructor should never be called manually. Those instrumenting tracing should use
+   * `Sentry.startTransaction()`, and internal methods should use `hub.startSpan()`.
    * @internal
    * @hideconstructor
    * @hidden

packages/minimal/src/index.ts

@@ -169,10 +169,21 @@ export function _callOnClient(method: string, ...args: any[]): void {
 }
 
 /**
- * This starts a Transaction and is considered the entry point to do manual tracing. You can add child spans
- * to a transactions. After that more children can be added to created spans to buld a tree structure.
- * This function returns a Transaction and you need to keep track of the instance yourself. When you call `.finsh()` on
- * a transaction it will be sent to Sentry.
+ * Starts a new transaction and returns it. This is the entry point to manual
+ * tracing instrumentation.
+ *
+ * A tree structure can be built by adding child spans to the transaction, and
+ * child spans to other spans. To start a new child span within the transaction
+ * or any span, call the respective `.startChild()` method.
+ *
+ * Every child span must be finished before the transaction is finished,
+ * otherwise the unfinished spans are discarded.
+ *
+ * The transaction must be finished with a call to its `.finish()` method, at
+ * which point the transaction with all its finished child spans will be sent to
+ * Sentry.
+ *
+ * @param context Properties with which the Transaction should be created.
  */
 export function startTransaction(transactionContext: TransactionContext): Transaction {
   return callOnHub<Transaction>('startSpan', {

packages/types/src/hub.ts

@@ -174,10 +174,11 @@ export interface Hub {
   traceHeaders(): { [key: string]: string };
 
   /**
-   * This functions starts either a Span or a Transaction (depending on the argument passed).
-   * If there is a Span on the Scope we use the `trace_id` for all other created Transactions / Spans as a reference.
+   * Starts either a new Span or a new Transaction, depending on the context.
+   * If there is an existing Span on the Scope, then a new Span will be
+   * started as its child.
    *
-   * @param context Properties with which the Transaction/Span should be created
+   * @param context Properties with which the Transaction/Span should be created.
    */
   startSpan(context: SpanContext | TransactionContext): Transaction | Span;
 }