docs: clean up headerdocs (#2829)

Sources/Sentry/Public/SentryAttachment.h

@@ -11,55 +11,47 @@ NS_SWIFT_NAME(Attachment)
 SENTRY_NO_INIT
 
 /**
- * Initializes an attachment with data. Sets the content type to "application/octet-stream".
- *
+ * Initializes an attachment with data. Sets the content type to @c "application/octet-stream".
  * @param data The data for the attachment.
  * @param filename The name of the attachment to display in Sentry.
  */
 - (instancetype)initWithData:(NSData *)data filename:(NSString *)filename;
 
 /**
  * Initializes an attachment with data.
- *
  * @param data The data for the attachment.
  * @param filename The name of the attachment to display in Sentry.
- * @param contentType The content type of the attachment. Default is "application/octet-stream".
+ * @param contentType The content type of the attachment. @c Default is "application/octet-stream".
  */
 - (instancetype)initWithData:(NSData *)data
                     filename:(NSString *)filename
                  contentType:(nullable NSString *)contentType;
 
 /**
- * Initializes an attachment with a path. Uses the last path compontent of the path as a filename
- * and sets the content type to "application/octet-stream".
- *
+ * Initializes an attachment with a path. Uses the last path component of the path as a filename
+ * and sets the content type to @c "application/octet-stream".
  * @discussion The file located at the pathname is read lazily when the SDK captures an event or
  * transaction not when the attachment is initialized.
- *
  * @param path The path of the file whose contents you want to upload to Sentry.
  */
 - (instancetype)initWithPath:(NSString *)path;
 
 /**
- * Initializes an attachment with a path. Sets the content type to "application/octet-stream".
- *
- * @discussion The file located at the pathname is read lazily when the SDK captures an event or
+ * Initializes an attachment with a path. Sets the content type to @c "application/octet-stream".
+ * @discussion The specified file is read lazily when the SDK captures an event or
  * transaction not when the attachment is initialized.
- *
  * @param path The path of the file whose contents you want to upload to Sentry.
  * @param filename The name of the attachment to display in Sentry.
  */
 - (instancetype)initWithPath:(NSString *)path filename:(NSString *)filename;
 
 /**
  * Initializes an attachment with a path.
- *
- * @discussion The file located at the pathname is read lazily when the SDK captures an event or
+ * @discussion The specifid file is read lazily when the SDK captures an event or
  * transaction not when the attachment is initialized.
- *
  * @param path The path of the file whose contents you want to upload to Sentry.
  * @param filename The name of the attachment to display in Sentry.
- * @param contentType The content type of the attachment. Default is "application/octet-stream".
+ * @param contentType The content type of the attachment. Default is @c "application/octet-stream".
  */
 - (instancetype)initWithPath:(NSString *)path
                     filename:(NSString *)filename

Sources/Sentry/Public/SentryBreadcrumb.h

@@ -19,7 +19,7 @@ NS_SWIFT_NAME(Breadcrumb)
 @property (nonatomic, copy) NSString *category;
 
 /**
- * NSDate when the breadcrumb happened
+ * @c NSDate when the breadcrumb happened
  */
 @property (nonatomic, strong) NSDate *_Nullable timestamp;
 
@@ -40,11 +40,9 @@ NS_SWIFT_NAME(Breadcrumb)
 @property (nonatomic, strong) NSDictionary<NSString *, id> *_Nullable data;
 
 /**
- * Initializer for SentryBreadcrumb
- *
+ * Initializer for @c SentryBreadcrumb
  * @param level SentryLevel
  * @param category String
- * @return SentryBreadcrumb
  */
 - (instancetype)initWithLevel:(SentryLevel)level category:(NSString *)category;
 - (instancetype)init;

Sources/Sentry/Public/SentryClient.h

@@ -13,96 +13,78 @@ SENTRY_NO_INIT
 @property (nonatomic, strong) SentryOptions *options;
 
 /**
- * Initializes a SentryClient. Pass in an dictionary of options.
- *
+ * Initializes a @c SentryClient. Pass in a dictionary of options.
  * @param options Options dictionary
- * @return SentryClient
+ * @return An initialized @c SentryClient or @c nil if an error occurred.
  */
 - (_Nullable instancetype)initWithOptions:(SentryOptions *)options;
 
 /**
  * Captures a manually created event and sends it to Sentry.
- *
  * @param event The event to send to Sentry.
- *
- * @return The SentryId of the event or SentryId.empty if the event is not sent.
+ * @return The @c SentryId of the event or @c SentryId.empty if the event is not sent.
  */
 - (SentryId *)captureEvent:(SentryEvent *)event NS_SWIFT_NAME(capture(event:));
 
 /**
  * Captures a manually created event and sends it to Sentry.
- *
  * @param event The event to send to Sentry.
  * @param scope The scope containing event metadata.
- *
- * @return The SentryId of the event or SentryId.empty if the event is not sent.
+ * @return The @c SentryId of the event or @c SentryId.empty if the event is not sent.
  */
 - (SentryId *)captureEvent:(SentryEvent *)event
                  withScope:(SentryScope *)scope NS_SWIFT_NAME(capture(event:scope:));
 
 /**
  * Captures an error event and sends it to Sentry.
- *
  * @param error The error to send to Sentry.
- *
- * @return The SentryId of the event or SentryId.empty if the event is not sent.
+ * @return The @c SentryId of the event or @c SentryId.empty if the event is not sent.
  */
 - (SentryId *)captureError:(NSError *)error NS_SWIFT_NAME(capture(error:));
 
 /**
  * Captures an error event and sends it to Sentry.
- *
  * @param error The error to send to Sentry.
  * @param scope The scope containing event metadata.
- *
- * @return The SentryId of the event or SentryId.empty if the event is not sent.
+ * @return The @c SentryId of the event or @c SentryId.empty if the event is not sent.
  */
 - (SentryId *)captureError:(NSError *)error
                  withScope:(SentryScope *)scope NS_SWIFT_NAME(capture(error:scope:));
 
 /**
  * Captures an exception event and sends it to Sentry.
- *
  * @param exception The exception to send to Sentry.
- *
- * @return The SentryId of the event or SentryId.empty if the event is not sent.
+ * @return The @c SentryId of the event or @c SentryId.empty if the event is not sent.
  */
 - (SentryId *)captureException:(NSException *)exception NS_SWIFT_NAME(capture(exception:));
 
 /**
  * Captures an exception event and sends it to Sentry.
- *
  * @param exception The exception to send to Sentry.
  * @param scope The scope containing event metadata.
- *
- * @return The SentryId of the event or SentryId.empty if the event is not sent.
+ * @return The @c SentryId of the event or @c SentryId.empty if the event is not sent.
  */
 - (SentryId *)captureException:(NSException *)exception
                      withScope:(SentryScope *)scope NS_SWIFT_NAME(capture(exception:scope:));
 
 /**
  * Captures a message event and sends it to Sentry.
- *
  * @param message The message to send to Sentry.
- *
- * @return The SentryId of the event or SentryId.empty if the event is not sent.
+ * @return The @c SentryId of the event or @c SentryId.empty if the event is not sent.
  */
 - (SentryId *)captureMessage:(NSString *)message NS_SWIFT_NAME(capture(message:));
 
 /**
  * Captures a message event and sends it to Sentry.
- *
  * @param message The message to send to Sentry.
  * @param scope The scope containing event metadata.
- *
- * @return The SentryId of the event or SentryId.empty if the event is not sent.
+ * @return The @c SentryId of the event or @c SentryId.empty if the event is not sent.
  */
 - (SentryId *)captureMessage:(NSString *)message
                    withScope:(SentryScope *)scope NS_SWIFT_NAME(capture(message:scope:));
 
 /**
  * Captures a manually created user feedback and sends it to Sentry.
- *
  * @param userFeedback The user feedback to send to Sentry.
  */
 - (void)captureUserFeedback:(SentryUserFeedback *)userFeedback
@@ -112,13 +94,12 @@ SENTRY_NO_INIT
  * Waits synchronously for the SDK to flush out all queued and cached items for up to the specified
  * timeout in seconds. If there is no internet connection, the function returns immediately. The SDK
  * doesn't dispose the client or the hub.
- *
  * @param timeout The time to wait for the SDK to complete the flush.
  */
 - (void)flush:(NSTimeInterval)timeout NS_SWIFT_NAME(flush(timeout:));
 
 /**
- * Disables the client and calls flush with ``SentryOptions/shutdownTimeInterval``.
+ * Disables the client and calls flush with @c SentryOptions.shutdownTimeInterval .
  */
 - (void)close;
 

Sources/Sentry/Public/SentryDebugImageProvider.h

@@ -14,21 +14,20 @@ NS_ASSUME_NONNULL_BEGIN
 
 /**
  * Returns a list of debug images that are being referenced in the given threads.
- *
- * @param threads A list of SentryThread that may or may not contains a stacktrace.
+ * @param threads A list of @c SentryThread that may or may not contain stacktracse.
  */
 - (NSArray<SentryDebugMeta *> *)getDebugImagesForThreads:(NSArray<SentryThread *> *)threads;
 
 /**
  * Returns a list of debug images that are being referenced by the given frames.
- *
  * @param frames A list of stack frames.
  */
 - (NSArray<SentryDebugMeta *> *)getDebugImagesForFrames:(NSArray<SentryFrame *> *)frames;
 
 /**
- * Returns the current list of debug images. Be aware that the SentryDebugMeta is actually
- * describing a debug image. This class should be renamed to SentryDebugImage in a future version.
+ * Returns the current list of debug images. Be aware that the @c SentryDebugMeta is actually
+ * describing a debug image.
+ * @todo This class should be renamed to @c SentryDebugImage in a future version.
  */
 - (NSArray<SentryDebugMeta *> *)getDebugImages;
 

Sources/Sentry/Public/SentryDebugMeta.h

@@ -5,27 +5,25 @@
 NS_ASSUME_NONNULL_BEGIN
 
 /**
- * This class is actually a DebugImage:
- * https://develop.sentry.dev/sdk/event-payloads/debugmeta/#debug-images and should be renamed to
- * SentryDebugImage in a future version.
- *
  * Contains information about a loaded library in the process and the memory address.
- *
  * @discussion Since 8.2.0, the SDK changed the debug image type from "apple" to "macho". For macho,
- * the SDK now sends ``debugID`` instead of ``uuid``, and ``codeFile`` instead of ``name``. For more
+ * the SDK now sends @c debugID instead of @c uuid , and @c codeFile instead of @c name . For more
  * information check https://develop.sentry.dev/sdk/event-payloads/debugmeta/#mach-o-images.
+ * @todo This class is actually a DebugImage:
+ * https://develop.sentry.dev/sdk/event-payloads/debugmeta/#debug-images and should be renamed to
+ * @c SentryDebugImage in a future version.
  */
 NS_SWIFT_NAME(DebugMeta)
 @interface SentryDebugMeta : NSObject <SentrySerializable>
 
 /**
- * The UUID of the image. Use ``debugID`` when using ``type`` "macho".
+ * The UUID of the image. Use @c debugID when using "macho" as the @c type .
  */
 @property (nonatomic, copy) NSString *_Nullable uuid;
 
 /**
- * Identifier of the dynamic library or executable. It is the value of the LC_UUID load command in
- * the Mach header, formatted as UUID.
+ * Identifier of the dynamic library or executable. It is the value of the @c LC_UUID load command
+ * in the Mach header, formatted as UUID.
  */
 @property (nonatomic, copy) NSString *_Nullable debugID;
 
@@ -35,7 +33,7 @@ NS_SWIFT_NAME(DebugMeta)
 @property (nonatomic, copy) NSString *_Nullable type;
 
 /**
- * Name of the image. Use ``codeFile`` when using ``type`` "macho".
+ * Name of the image. Use @c codeFile when using "macho" as the @c type .
  */
 @property (nonatomic, copy) NSString *_Nullable name;
 

Sources/Sentry/Public/SentryDefines.h

@@ -37,14 +37,14 @@
 typedef void (^SentryRequestFinished)(NSError *_Nullable error);
 
 /**
- * Block used for request operation finished, shouldDiscardEvent is YES if event
+ * Block used for request operation finished, @c shouldDiscardEvent is @c YES if event
  * should be deleted regardless if an error occurred or not
  */
 typedef void (^SentryRequestOperationFinished)(
     NSHTTPURLResponse *_Nullable response, NSError *_Nullable error);
 /**
  * Block can be used to mutate a breadcrumb before it's added to the scope.
- * To avoid adding the breadcrumb altogether, return nil instead.
+ * To avoid adding the breadcrumb altogether, return @c nil instead.
  */
 typedef SentryBreadcrumb *_Nullable (^SentryBeforeBreadcrumbCallback)(
     SentryBreadcrumb *_Nonnull breadcrumb);
@@ -71,24 +71,21 @@ typedef BOOL (^SentryShouldQueueEvent)(
 
 /**
  * Function pointer for a sampler callback.
- *
  * @param samplingContext context of the sampling.
- *
- * @return A sample rate that is >= 0.0 and <= 1.0 or NIL if no sampling decision has been taken..
- * When returning a value out of range the SDK uses the default of 0.
+ * @return A sample rate that is >=  @c 0.0 and \<= @c 1.0 or @c nil if no sampling decision has
+ * been taken. When returning a value out of range the SDK uses the default of @c 0.
  */
 typedef NSNumber *_Nullable (^SentryTracesSamplerCallback)(
     SentrySamplingContext *_Nonnull samplingContext);
 
 /**
  * Function pointer for span manipulation.
- *
  * @param span The span to be used.
  */
 typedef void (^SentrySpanCallback)(id<SentrySpan> _Nullable span);
 
 /**
- * Loglevel
+ * Log level.
  */
 typedef NS_ENUM(NSInteger, SentryLogLevel) {
     kSentryLogLevelNone = 1,
@@ -98,7 +95,7 @@ typedef NS_ENUM(NSInteger, SentryLogLevel) {
 };
 
 /**
- * Sentry level
+ * Sentry level.
  */
 typedef NS_ENUM(NSUInteger, SentryLevel) {
     // Defaults to None which doesn't get serialized
@@ -112,7 +109,7 @@ typedef NS_ENUM(NSUInteger, SentryLevel) {
 };
 
 /**
- * Static internal helper to convert enum to string
+ * Static internal helper to convert enum to string.
  */
 static DEPRECATED_MSG_ATTRIBUTE(
     "Use nameForSentryLevel() instead.") NSString *_Nonnull const SentryLevelNames[]
@@ -128,7 +125,7 @@ static DEPRECATED_MSG_ATTRIBUTE(
 static NSUInteger const defaultMaxBreadcrumbs = 100;
 
 /**
- * Transaction name source
+ * Transaction name source.
  */
 typedef NS_ENUM(NSInteger, SentryTransactionNameSource) {
     kSentryTransactionNameSourceCustom = 0,