Standardization of our documentation comments

sdk/eventgrid/eventgrid/src/consumer.ts

@@ -54,7 +54,7 @@ export class EventGridConsumer {
   /**
    * Deserializes events encoded in the Event Grid schema.
    *
-   * @param encodedEvents the JSON encoded representation of either a single event or an array of
+   * @param encodedEvents - the JSON encoded representation of either a single event or an array of
    * events, encoded in the Event Grid Schema.
    */
   public async deserializeEventGridEvents(
@@ -64,7 +64,7 @@ export class EventGridConsumer {
   /**
    * Deserializes events encoded in the Event Grid schema.
    *
-   * @param encodedEvents an object representing a single event, encoded in the Event Grid schema.
+   * @param encodedEvents - an object representing a single event, encoded in the Event Grid schema.
    */
   public async deserializeEventGridEvents(
     encodedEvents: object
@@ -98,15 +98,15 @@ export class EventGridConsumer {
   /**
    * Deserializes events encoded in the Cloud Events 1.0 schema.
    *
-   * @param encodedEvents the JSON encoded representation of either a single event or an array of
+   * @param encodedEvents - the JSON encoded representation of either a single event or an array of
    * events, encoded in the Cloud Events 1.0 Schema.
    */
   public async deserializeCloudEvents(encodedEvents: string): Promise<CloudEvent<unknown>[]>;
 
   /**
    * Deserializes events encoded in the Cloud Events 1.0 schema.
    *
-   * @param encodedEvents an object representing a single event, encoded in the Cloud Events 1.0 schema.
+   * @param encodedEvents - an object representing a single event, encoded in the Cloud Events 1.0 schema.
    */
   public async deserializeCloudEvents(encodedEvents: object): Promise<CloudEvent<unknown>[]>;
   public async deserializeCloudEvents(

sdk/eventgrid/eventgrid/src/cryptoHelpers.browser.ts

@@ -5,7 +5,6 @@
 
 /**
  * @internal
- * @ignore
  */
 export async function sha256Hmac(secret: string, stringToSign: string): Promise<string> {
   const key = await self.crypto.subtle.importKey(

sdk/eventgrid/eventgrid/src/cryptoHelpers.ts

@@ -5,7 +5,6 @@ import { createHmac } from "crypto";
 
 /**
  * @internal
- * @ignore
  */
 export async function sha256Hmac(secret: string, stringToSign: string): Promise<string> {
   const decodedSecret = Buffer.from(secret, "base64");

sdk/eventgrid/eventgrid/src/eventGridClient.ts

@@ -88,9 +88,9 @@ export class EventGridPublisherClient {
    * );
    * ```
    *
-   * @param endpointUrl The URL to the EventGrid endpoint, e.g. https://eg-topic.westus2-1.eventgrid.azure.net/api/events
-   * @param credential Used to authenticate requests to the service.
-   * @param options Used to configure the Event Grid Client
+   * @param endpointUrl - The URL to the EventGrid endpoint, e.g. https://eg-topic.westus2-1.eventgrid.azure.net/api/events
+   * @param credential - Used to authenticate requests to the service.
+   * @param options - Used to configure the Event Grid Client
    */
   constructor(
     endpointUrl: string,
@@ -124,9 +124,9 @@ export class EventGridPublisherClient {
   }
 
   /**
-   * Publishes events in the Event Grid scheama. The topic must be configured to expect events in the Event Grid schema.
+   * Publishes events in the Event Grid schema. The topic must be configured to expect events in the Event Grid schema.
    *
-   * @param message One or more events to publish
+   * @param message - One or more events to publish
    */
   async sendEvents(
     events: SendEventGridEventInput<any>[],
@@ -155,7 +155,7 @@ export class EventGridPublisherClient {
   /**
    * Publishes events in the Cloud Events 1.0 schema. The topic must be configured to expect events in the Cloud Events 1.0 schema.
    *
-   * @param message One or more events to publish
+   * @param message - One or more events to publish
    */
   async sendCloudEvents(
     events: SendCloudEventInput<any>[],
@@ -184,7 +184,7 @@ export class EventGridPublisherClient {
   /**
    * Publishes events written using a custom schema. The topic must be configured to expect events in a custom schema.
    *
-   * @param message One or more events to publish
+   * @param message - One or more events to publish
    */
   async sendCustomSchemaEvents(
     events: Record<string, any>[],

sdk/eventgrid/eventgrid/src/generateSharedAccessSignature.ts

@@ -18,10 +18,10 @@ export interface GenerateSharedAccessSignatureOptions {
  * Generate a shared access signature, which allows a client to send events to an Event Grid Topic or Domain for a limited period of time. This
  * function may only be called when the EventGridPublisherClient was constructed with a KeyCredential instance.
  *
- * @param endpointUrl The endpoint for the topic or domain you wish to generate a shared access signature for.
- * @param credential The credential to use when generating the shared access signatrue.
- * @param expiresOn The time at which the shared access signature is no longer valid.
- * @param options Options to control how the signature is generated.
+ * @param endpointUrl - The endpoint for the topic or domain you wish to generate a shared access signature for.
+ * @param credential - The credential to use when generating the shared access signatrue.
+ * @param expiresOn - The time at which the shared access signature is no longer valid.
+ * @param options - Options to control how the signature is generated.
  */
 export async function generateSharedAccessSignature(
   endpointUrl: string,

sdk/eventgrid/eventgrid/src/logger.ts

@@ -4,6 +4,6 @@
 import { createClientLogger } from "@azure/logger";
 
 /**
- * The @azure/logger configuration for this package.
+ * The \@azure/logger configuration for this package.
  */
 export const logger = createClientLogger("eventgrid");

sdk/eventgrid/eventgrid/src/predicates.ts

@@ -209,7 +209,7 @@ export type KnownSystemEventTypes =
 /**
  * A mapping of event type names to event data type interfaces.
  *
- * @ignore
+ * @internal
  */
 export interface SystemEventNameToEventData {
   /** An interface for the event data of a "Microsoft.Communication.ChatMessageReceived" event. */
@@ -411,7 +411,7 @@ export interface SystemEventNameToEventData {
 /**
  * isCloudEventLike returns "true" when the event is a CloudEvent
  *
- * @param o Either an EventGrid our CloudEvent event.
+ * @param o - Either an EventGrid our CloudEvent event.
  */
 function isCloudEventLike(
   o: EventGridEvent<unknown> | CloudEvent<unknown>
@@ -424,8 +424,8 @@ function isCloudEventLike(
  * TypeScript, this function acts as a custom type guard and allows the TypeScript compiler to
  * identify the underlying data
  *
- * @param eventType The type of system event to check for, e.g., "Microsoft.AppConfiguration.KeyValueDeleted"
- * @param event The event to test.
+ * @param eventType - The type of system event to check for, e.g., "Microsoft.AppConfiguration.KeyValueDeleted"
+ * @param event - The event to test.
  */
 export function isSystemEvent<T extends KnownSystemEventTypes>(
   eventType: T,
@@ -437,8 +437,8 @@ export function isSystemEvent<T extends KnownSystemEventTypes>(
  * TypeScript, this function acts as a custom type guard and allows the TypeScript compiler to
  * identify the underlying data
  *
- * @param eventType The type of system event to check for, e.g., "Microsoft.AppConfiguration.KeyValueDeleted"
- * @param event The event to test.
+ * @param eventType - The type of system event to check for, e.g., "Microsoft.AppConfiguration.KeyValueDeleted"
+ * @param event - The event to test.
  */
 export function isSystemEvent<T extends KnownSystemEventTypes>(
   eventType: T,

sdk/eventgrid/eventgrid/src/sharedAccessSignitureCredential.ts

@@ -31,7 +31,7 @@ export class EventGridSharedAccessSignatureCredential implements SignatureCreden
    * Create an instance of an EventGridSharedAccessSignatureCredential for use
    * with a service client.
    *
-   * @param {string} signature the signature to use in authentication
+   * @param signature - The signature to use in authentication
    */
   constructor(signature: string) {
     if (!signature) {
@@ -47,7 +47,7 @@ export class EventGridSharedAccessSignatureCredential implements SignatureCreden
    * Updates will take effect upon the next request after
    * updating the signature value.
    *
-   * @param {string} newSignature the new signature value to be used
+   * @param newSignature - The new signature value to be used
    */
   public update(newSignature: string): void {
     this._signature = newSignature;

sdk/eventgrid/eventgrid/src/tracing.ts

@@ -9,9 +9,9 @@ type OperationTracingOptions = OperationOptions["tracingOptions"];
 
 /**
  * Creates a span using the global tracer.
- * @ignore
- * @param name The name of the operation being performed.
- * @param tracingOptions The options for the underlying http request.
+ * @internal
+ * @param name - The name of the operation being performed.
+ * @param tracingOptions - The options for the underlying http request.
  */
 export function createSpan<T extends OperationOptions>(
   operationName: string,

sdk/eventgrid/eventgrid/src/util.ts

@@ -14,7 +14,7 @@ import { KeyCredential } from "@azure/core-auth";
  *
  * The service expects a UTC time, so this method returns a string based on the UTC time of the provided Date.
  *
- * @param d The Date object to convert to a string.
+ * @param d - The Date object to convert to a string.
  */
 export function dateToServiceTimeString(d: Date): string {
   const month = d.getUTCMonth() + 1; // getUTCMonth returns 0-11 not 1-12.
@@ -39,7 +39,7 @@ export function dateToServiceTimeString(d: Date): string {
  * Returns `true` if the credential object is like the KeyCredential interface (i.e. it has a
  * key property).
  *
- * @param credential the object to test
+ * @param credential - The object to test
  */
 export function isKeyCredentialLike(o: unknown): o is KeyCredential {
   const castO = o as {