add comments and fix docstring

Author: lobsterkatie

packages/types/src/severity.ts

@@ -18,6 +18,6 @@ export enum Severity {
   Critical = 'critical',
 }
 
-// TODO: in v7, these can disappear, because they now also exist in `@sentry/utils`. (Having them there rather than here
-// is nice because then it enforces the idea that only types are exported from `@sentry/types`.)
+// Note: If this is ever changed, the `validSeverityLevels` array in `@sentry/utils` needs to be changed, also. (See
+// note there for why we can't derive one from the other.)
 export type SeverityLevel = 'fatal' | 'error' | 'warning' | 'log' | 'info' | 'debug' | 'critical';

packages/utils/src/severity.ts

@@ -1,11 +1,23 @@
 import { Severity, SeverityLevel } from '@sentry/types';
 
+// TODO: Should `severityFromString` be deprecated?
+
+// Note: Ideally the `SeverityLevel` type would be derived from `validSeverityLevels`, but that would mean either
+//
+// a) moving `validSeverityLevels` to `@sentry/types`,
+// b) moving the`SeverityLevel` type here, or
+// c) importing `validSeverityLevels` from here into `@sentry/types`.
+//
+// Option A would make `@sentry/types` a runtime dependency of `@sentry/utils` (not good), and options B and C would
+// create a circular dependency between `@sentry/types` and `@sentry/utils` (also not good). So a TODO accompanying the
+// type, reminding anyone who changes it to change this list also, will have to do.
+
 export const validSeverityLevels = ['fatal', 'error', 'warning', 'log', 'info', 'debug', 'critical'];
 
 /**
- * Converts a string-based level into a {@link Severity}.
+ * Converts a string-based level into a member of the {@link Severity} enum.
  *
- * @param level string representation of Severity
+ * @param level String representation of Severity
  * @returns Severity
  */
 export function severityFromString(level: SeverityLevel | string): Severity {