chore(clerk-react,nextjs): Improve comments

packages/nextjs/src/app-router/server/auth.ts

@@ -11,7 +11,8 @@ type AuthSignedIn = AuthObjectWithoutResources<
   SignedInAuthObject & {
     /**
      * @experimental
-     * This function is experimental as it throws a Nextjs notFound error if user is not authenticated or authorized
+     * This function is experimental as it throws a Nextjs notFound error if user is not authenticated or authorized.
+     * In the future we would investigate a way to throw a more appropriate error that clearly describes the not authorized of authenticated status.
      */
     protect: (
       params?:
@@ -25,7 +26,8 @@ type AuthSignedOut = AuthObjectWithoutResources<
   SignedOutAuthObject & {
     /**
      * @experimental
-     * This function is experimental as it throws a Nextjs notFound error if user is not authenticated or authorized
+     * This function is experimental as it throws a Nextjs notFound error if user is not authenticated or authorized.
+     * In the future we would investigate a way to throw a more appropriate error that clearly describes the not authorized of authenticated status.
      */
     protect: never;
   }

packages/nextjs/src/app-router/server/controlComponents.tsx

@@ -18,23 +18,24 @@ export function SignedOut(props: React.PropsWithChildren) {
 type ProtectServerComponentProps = React.ComponentProps<typeof ProtectClientComponent>;
 
 /**
- * Use `<Protect/>` in order to prevent unauthenticated or unauthorized user from accessing the children passed to the component.
+ * Use `<Protect/>` in order to prevent unauthenticated or unauthorized users from accessing the children passed to the component.
  *
  * Examples:
  * ```
  * <Protect permission="a_permission_key" />
  * <Protect role="a_role_key" />
  * <Protect condition={(has) => has({permission:"a_permission_key"})} />
  * <Protect condition={(has) => has({role:"a_role_key"})} />
- * <Protect fallback={<p>Unauthorized</p>}/>
+ * <Protect fallback={<p>Unauthorized</p>} />
  * ```
  */
 export function Protect(props: ProtectServerComponentProps) {
   const { children, fallback, ...restAuthorizedParams } = props;
   const { has, userId } = auth();
 
   /**
-   * If neither of the authorization params are passed behave as the `<SignedIn/>`
+   * If neither of the authorization params are passed behave as the `<SignedIn/>`.
+   * If fallback is present render that instead of rendering nothing.
    */
   if (!restAuthorizedParams.condition && !restAuthorizedParams.role && !restAuthorizedParams.permission) {
     if (userId) {
@@ -58,7 +59,7 @@ export function Protect(props: ProtectServerComponentProps) {
   }
 
   /**
-   * Fallback to custom ui or null if authorization checks failed
+   * Fallback to UI provided by user or `null` if authorization checks failed
    */
   return <>{fallback ?? null}</>;
 }

packages/react/src/components/controlComponents.tsx

@@ -74,22 +74,23 @@ type ProtectProps = React.PropsWithChildren<
 >;
 
 /**
- * Use `<Protect/>` in order to prevent unauthenticated or unauthorized user from accessing the children passed to the component.
+ * Use `<Protect/>` in order to prevent unauthenticated or unauthorized users from accessing the children passed to the component.
  *
  * Examples:
  * ```
  * <Protect permission="a_permission_key" />
  * <Protect role="a_role_key" />
  * <Protect condition={(has) => has({permission:"a_permission_key"})} />
  * <Protect condition={(has) => has({role:"a_role_key"})} />
- * <Protect fallback={<p>Unauthorized</p>}/>
+ * <Protect fallback={<p>Unauthorized</p>} />
  * ```
  */
 export const Protect = ({ children, fallback, ...restAuthorizedParams }: ProtectProps) => {
   const { has, userId } = useAuth();
 
   /**
-   * If neither of the authorization params are passed behave as the `<SignedIn/>`
+   * If neither of the authorization params are passed behave as the `<SignedIn/>`.
+   * If fallback is present render that instead of rendering nothing.
    */
   if (!restAuthorizedParams.condition && !restAuthorizedParams.role && !restAuthorizedParams.permission) {
     if (userId) {
@@ -113,7 +114,7 @@ export const Protect = ({ children, fallback, ...restAuthorizedParams }: Protect
   }
 
   /**
-   * Fallback to custom ui or null if authorization checks failed
+   * Fallback to UI provided by user or `null` if authorization checks failed
    */
   return <>{fallback ?? null}</>;
 };