mirror of
https://github.com/Effect-TS/effect.git
synced 2026-11-20 01:53:23 +08:00
4.0 KiB
4.0 KiB
JSDoc Patterns
@category Guidance
When adding or vetting JSDoc categories in public source files:
- Use exactly one
@categorytag for each public JSDoc block that represents a documented API. - Use shared categories consistently across the repository. Domain-specific categories are allowed when they improve navigation within a file or package, but avoid one-off categories unless they name an important API/domain concept.
- Prefer lowercase category names by default, plural nouns for API buckets, and gerunds for operation families.
- Preserve canonical casing for acronyms and proper API/domain names, such as
type IDs,DateTime,Undici, andHttpAgent. - Prefer shared API-shape categories for common Effect/library patterns, and use domain-topic categories only when they provide clearer navigation.
- Avoid vague fallback categories. Use
utilsonly when no more specific shared or domain category fits; avoidcommonand do not usemisc.
Common Shared Categories
- API shapes:
constructors,destructors,models,schemas,guards,predicates,getters,accessors,instances,constants,protocols,prototypes,re-exports,unsafe,testing - Effect/service concepts:
services,tags,layers,context,resource management,running - Type-level APIs:
utility typesfor type-level helpers/contracts; usemodelsfor exported type/interface/class shapes that represent domain data - Error APIs:
errorsfor error models/classes/types,error handlingfor recovery/catching/mapping APIs - Operations:
combinators,filtering,mapping,sequencing,zipping,converting,transforming,folding,splitting,concatenating - Encoding/data formats:
encoding,decoding,serialization - Observability:
tracing,metrics,logging - Other common concepts:
annotations,references,symbols,type IDs,configuration,math,comparisons,ordering,utils
Alias Normalization
Normalize high-confidence aliases, for example:
Constructors/constructor->constructorsLayers/layer->layersModels/Model/model->modelsCombinators->combinatorsAccessors->accessorsGuards/Guard->guardsMiddleware->middlewareerror->errorsError Handling->error handlingEquivalence->instancesScope->resource managementWrapper->wrappingRate Limiting->rate limitingMemory->memoryConfig->configurationEpoch->constantsRegistry->servicesReflection->reflectionModifiers->modifiersTesting->testingToken->tokenGrouping->groupingtranferables->transferablesComputer Use->computer useText Editor->text editorTool Search->tool searchType IDs/type ids->type IDsServices/Service/service->servicesRe-exports->re-exportsprotocol->protocolsResult->resultsBoundaries->boundariesTaking->takingorder->orderingdate & time->DateTimeserialization / deserialization->serializationconversions->convertingtransformations->transformingResource Management & Finalization->resource managementRun main->runningprovider options->configurationutilities/Utilities->utils
Distinctions
Keep these distinctions:
servicesare service contracts/shapes,tagsidentify services inContext, andlayersprovide services.gettersretrieve values/properties, whileaccessorsare contextual service or environment access helpers.errorsare error data types, whileerror handlingis for APIs that handle failures.modelsdescribe domain/API data structures, whileschemasare schema values/combinators andutility typesare type-level helpers/contracts.guardsare TypeScript type guards,predicatesare boolean tests, andfilteringis for filtering operations.