Restructure documentation: organize types by category and add function naming conventions

- Updated cabal file description with complete type listings organized by category
- Organized exports in PostgresqlTypes module by category with section comments
- Added comprehensive function naming convention documentation (normalizeFrom*, refineFrom*, to*)
- Updated README to reference cabal file and module documentation for consistency
- Maintained consistency across .cabal, README, and PostgresqlTypes module

Co-authored-by: nikita-volkov <1560937+nikita-volkov@users.noreply.github.com>

Author: Copilot

README.md

@@ -9,6 +9,18 @@ Precise Haskell representations of PostgreSQL data types with mappings to and fr
 
 In active development, but already working and exhaustively tested.
 
+## Documentation
+
+For complete documentation including:
+- Full list of supported types organized by category
+- Function naming conventions (normalizeFrom*, refineFrom*, to*)
+- Type safety guarantees and valid ranges
+- Usage examples
+
+Please refer to:
+- **[Package documentation on Hackage](https://hackage.haskell.org/package/postgresql-types)** - Complete API reference
+- **[Module documentation (PostgresqlTypes)](https://nikita-volkov.github.io/postgresql-types/PostgresqlTypes.html)** - Type listings and usage examples
+
 ## Key Features
 
 ### Ecosystem Integration
@@ -20,21 +32,24 @@ Adapter packages provide integrations for major PostgreSQL client libraries:
 
 ### Supported Types
 
-This package provides support for nearly all PostgreSQL data types, including but not limited to:
-
-- Numeric types: `Int2`, `Int4`, `Int8`, `Float4`, `Float8`, `Numeric`
-- Character types: `Char`, `Varchar`, `Text`
-- Boolean type: `Bool`
-- Date/time types: `Date`, `Time`, `Timestamp`, `Timestamptz`, `Interval`
-- Network address types: `Inet`, `Cidr`, `Macaddr`, `Macaddr8`
-- Geometric types: `Point`, `Line`, `Lseg`, `Box`, `Path`, `Polygon`, `Circle`
-- Bit string types: `Bit`, `Varbit`
-- UUID type: `Uuid`
-- JSON types: `Json`, `Jsonb`
-- Key-value types: `Hstore`
-- Range types: `Int4Range`, `Int8Range`, `NumRange`, `TsRange`, `TstzRange`, `DateRange`
-- Multirange types: `Int4Multirange`, `Int8Multirange`, `NumMultirange`, `TsMultirange`, `TstzMultirange`, `DateMultirange`
-- Array types for all of the above
+This package provides support for nearly all PostgreSQL data types, including:
+
+- **Numeric types**: Int2, Int4, Int8, Float4, Float8, Numeric, Money, Oid
+- **Character types**: Char, Varchar, Text, Bpchar
+- **Boolean type**: Bool
+- **Binary data**: Bytea
+- **Date/time types**: Date, Time, Timestamp, Timestamptz, Timetz, Interval
+- **Network address types**: Inet, Cidr, Macaddr, Macaddr8
+- **Geometric types**: Point, Line, Lseg, Box, Path, Polygon, Circle
+- **Bit string types**: Bit, Varbit
+- **UUID type**: Uuid
+- **JSON types**: Json, Jsonb
+- **Key-value types**: Hstore
+- **Range types**: Range (supporting int4range, int8range, numrange, tsrange, tstzrange, daterange)
+- **Multirange types**: Multirange (supporting int4multirange, int8multirange, etc.)
+- **Array types** for all of the above
+
+For detailed information about each type, see the [package documentation](https://hackage.haskell.org/package/postgresql-types).
 
 ### Type Safety & Valid Ranges
 
@@ -44,10 +59,11 @@ Values can only be created through explicit constructor functions, guaranteeing
 
 ### Type-Safe Constructors
 
-The library provides two types of constructors for each type:
+The library provides three types of functions for working with PostgreSQL types:
 
 - **Normalizing constructors** (prefix: `normalizeFrom*`) - Always succeed by clamping or canonicalizing input values to valid ranges
 - **Refining constructors** (prefix: `refineFrom*`) - Return `Maybe`, failing if the input is out of range
+- **Accessor functions** (prefix: `to*`) - Extract values from PostgreSQL types to common Haskell types
 
 This approach ensures that:
 - Type constructors remain hidden to protect invariants

postgresql-types.cabal

@@ -22,6 +22,158 @@ description:
 
   * postgresql-simple: <https://hackage-content.haskell.org/package/postgresql-simple-postgresql-types>
 
+  .
+
+  == Supported Types
+
+  This package provides support for nearly all PostgreSQL data types, organized by category:
+
+  .
+
+  === Numeric Types
+
+  * 'Int2' - 2-byte signed integer (@int2@ \/ @smallint@)
+
+  * 'Int4' - 4-byte signed integer (@int4@ \/ @integer@)
+
+  * 'Int8' - 8-byte signed integer (@int8@ \/ @bigint@)
+
+  * 'Float4' - Single-precision floating point (@float4@ \/ @real@)
+
+  * 'Float8' - Double-precision floating point (@float8@ \/ @double precision@)
+
+  * 'Numeric' - Arbitrary precision numeric (@numeric@ \/ @decimal@)
+
+  * 'Money' - Currency amount (@money@)
+
+  * 'Oid' - Object identifier (@oid@)
+
+  .
+
+  === Character Types
+
+  * 'Text' - Variable-length character string (@text@)
+
+  * 'Varchar' - Variable-length with limit (@varchar@)
+
+  * 'Char' - Single ASCII character (@char@)
+
+  * 'Bpchar' - Fixed-length character string (@char(n)@, @character(n)@, or @bpchar(n)@)
+
+  .
+
+  === Boolean Type
+
+  * 'Bool' - Boolean (@bool@)
+
+  .
+
+  === Binary Data
+
+  * 'Bytea' - Binary data (@bytea@)
+
+  .
+
+  === Date\/Time Types
+
+  * 'Date' - Calendar date (@date@)
+
+  * 'Time' - Time of day without time zone (@time@)
+
+  * 'Timestamp' - Date and time without time zone (@timestamp@)
+
+  * 'Timestamptz' - Date and time with time zone (@timestamptz@)
+
+  * 'Timetz' - Time of day with time zone (@timetz@)
+
+  * 'Interval' - Time interval (@interval@)
+
+  .
+
+  === Network Address Types
+
+  * 'Inet' - IPv4 or IPv6 host address (@inet@)
+
+  * 'Cidr' - IPv4 or IPv6 network address (@cidr@)
+
+  * 'Macaddr' - MAC address (@macaddr@)
+
+  * 'Macaddr8' - MAC address (EUI-64 format) (@macaddr8@)
+
+  .
+
+  === Geometric Types
+
+  * 'Point' - Point on a plane (@point@)
+
+  * 'Line' - Infinite line (@line@)
+
+  * 'Lseg' - Line segment (@lseg@)
+
+  * 'Box' - Rectangular box (@box@)
+
+  * 'Path' - Geometric path (@path@)
+
+  * 'Polygon' - Closed geometric path (@polygon@)
+
+  * 'Circle' - Circle (@circle@)
+
+  .
+
+  === Bit String Types
+
+  * 'Bit' - Fixed-length bit string (@bit@)
+
+  * 'Varbit' - Variable-length bit string (@varbit@)
+
+  .
+
+  === UUID Type
+
+  * 'Uuid' - Universally unique identifier (@uuid@)
+
+  .
+
+  === JSON Types
+
+  * 'Json' - JSON data (@json@)
+
+  * 'Jsonb' - Binary JSON data (@jsonb@)
+
+  .
+
+  === Key-Value Types
+
+  * 'Hstore' - Key-value store (@hstore@)
+
+  .
+
+  === Range Types
+
+  * 'Range' - Generic range type supporting int4range, int8range, numrange, tsrange, tstzrange, daterange
+
+  * 'Multirange' - Generic multirange type supporting int4multirange, int8multirange, etc.
+
+  .
+
+  === Array Types
+
+  Array types are available for all of the above types.
+
+  .
+
+  == Function Naming Conventions
+
+  The library provides three types of functions for working with PostgreSQL types:
+
+  .
+
+  * __Normalizing constructors__ (prefix: @normalizeFrom*@) - Always succeed by clamping or canonicalizing input values to valid ranges. Use these when you want to ensure a value is valid by transforming invalid inputs into valid ones (e.g., removing NUL bytes from text, clamping dates to PostgreSQL's supported range).
+
+  * __Refining constructors__ (prefix: @refineFrom*@) - Return 'Maybe', failing if the input is out of range or invalid. Use these when you want to validate that input data is already within valid PostgreSQL constraints.
+
+  * __Accessor functions__ (prefix: @to*@) - Extract values from PostgreSQL types to common Haskell types. These conversions are always safe and total.
+
 homepage: https://github.com/nikita-volkov/postgresql-types
 bug-reports: https://github.com/nikita-volkov/postgresql-types/issues
 author: Nikita Volkov <nikita.y.volkov@mail.ru>