docs: small inline docs improvements

Author: misterjoshua

Diff for: packages/tracer/src/Tracer.ts

@@ -373,6 +373,8 @@ class Tracer extends Utility implements TracerInterface {
             if (options?.captureError ?? true) {
               tracerRef.addErrorAsMetadata(error as Error);
             } else {
+              // Though we aren't adding the error as metadata, we should still
+              // mark the segment as having an error.
               tracerRef.getSegment().addErrorFlag();
             }
             throw error;
@@ -450,6 +452,8 @@ class Tracer extends Utility implements TracerInterface {
             if (options?.captureError ?? true) {
               tracerRef.addErrorAsMetadata(error as Error);
             } else {
+              // Though we aren't adding the error as metadata, we should still
+              // mark the segment as having an error.
               tracerRef.getSegment().addErrorFlag();
             }
 

Diff for: packages/tracer/src/types/Tracer.ts

@@ -36,7 +36,9 @@ type TracerOptions = {
  *
  * class MyThing {
  *   @tracer.captureMethod({ captureResponse: false, captureError: false })
- *   async myMethod() { ... }
+ *   myMethod(): string {
+ *     return 'foo bar';
+ *   }
  * }
  * ```
  */
@@ -55,7 +57,7 @@ type TracerCaptureMethodOptions = {
  *
  * class MyThing implements LambdaInterface {
  *   @tracer.captureLambdaHandler({ captureResponse: false, captureError: false })
- *   async handler() { ... }
+ *   async handler(_event: any, _context: any): Promise<void> {}
  * }
  * ```
  */