Document exceptions

[JeremyCaney]

Document, via <exception> tags, every member across the distributable libraries that throws.

Scope

• Direct throws
• Contract.* guards (decoded to their thrown type)
• Calls to curated validators (e.g., TopicFactory.ValidateKey(), BindingModelValidator.*), one hop only

Deferred

Exceptions that merely propagate up from deeper library calls, and BCL exceptions latent in implementations.

Notes

• Legacy <requires> tags (from Code Contracts) that describe a throw should be replaced by <exception>, with the type derived from the code (not the stale attribute)
  • Route each tag to a commit by its decoded type, not its exception= label
• Contractual throws should be documented on the interface so implementations inherit them via <inheritdoc/>
  • Only implementation-specific throws will be documented on the concrete type

Tasks

• Foundation
  • Correct inverted "Thrown when isValid returns true" bodies in Contract.cs, as the guard throws when false
  • Finalize the curated validator set (confirm e.g., ValidateKey() and BindingModelValidator.*)
  • Build a site inventory, classifying the non-generic Contract.Requires(), Contract.Assume() sites and the TopicRepositoryException throws (base, SqlTopicRepository) once
• By exception type
  • InvalidKeyException: ValidateKey() consumers, explicit Contract.Requires<InvalidKeyException>(), and direct throws (continues prior work)
  • ArgumentNullException: Explicit Contract.Requires<ArgumentNullException>(), Contract.Assume<ArgumentNullException>(), and bare Contract.Requires()
  • InvalidOperationException: Bool-expression Contract.Requires(), non-generic Contract.Assume(), and direct throws
  • ArgumentException: Explicit Contract.Requires<ArgumentException>() and direct throws
  • ArgumentOutOfRangeException: Explicit Contract.Requires<ArgumentOutOfRangeException>() and direct throws
    • Includes converting the stale maxHops <requires> tag here, which is labeled ArgumentException but throws ArgumentOutOfRangeException
  • ReferentialIntegrityException: Direct throws in the repository Delete(), Move(); put on ITopicRepository
  • TopicNotFoundException: Explicit Contract.Requires<TopicNotFoundException>() and direct throws; put on ITopicRepository
  • TopicRepositoryException: Direct throws; base go on ITopicRepository, SqlTopicRepository-only stay there
  • MappingModelValidationException: Direct throws, plus BindingModelValidator.* propagated one hop to the public MapAsync() entry points
  • TopicMappingException: Direct throws in mapping
  • InvalidTypeException: Direct throws in mapping
• Verify <GenerateDocumentationFile> is enabled for each distributable

Out of scope:

• The Obsolete/ folder
• NotImplementedException stubs
• The non-distributable *.Host, *.Tests, *.TestDoubles projects