feat: incresed tsdoc documentation a lot

docs/src/config.md

@@ -21,7 +21,8 @@ the defaults for all requests.
 - Type: `AxiosStorage`
 - Default: `buildMemoryStorage()`
 
-The object responsible to save, retrieve and serialize (if needed) cache data.
+A storage interface is the entity responsible for saving, retrieving and serializing data
+received from network and requested when a axios call is made.
 
 See the [Storages](./guide/storages.md) page for more information.
 
@@ -82,9 +83,9 @@ The possible returns are:
 ::: details Example of a custom headerInterpreter
 
 ```ts
-import { setupCache, type HeaderInterpreter } from 'axios-cache-interceptor';
+import { setupCache, type HeadersInterpreter } from 'axios-cache-interceptor';
 
-const myHeaderInterpreter: HeaderInterpreter = (headers) => {
+const myHeaderInterpreter: HeadersInterpreter = (headers) => {
   if (headers['x-my-custom-header']) {
     const seconds = Number(headers['x-my-custom-header']);
 

docs/src/config/request-specifics.md

@@ -21,19 +21,22 @@ the same way you do with the [global options](../config.md).
 - default: _(auto generated by the current
   [key generator](../guide/request-id.md#custom-generator))_
 
-You can override the request id used by this property.
-[See more about ids](../guide/request-id.md).
+The [Request ID](../guide/request-id.md) used in this request.
+
+It may have been generated by the [Key Generator](../guide/request-id.md#custom-generator)
+or a custom one provided by [`config.id`](./request-specifics.md#id)
 
 ## cache
 
 <Badge text="optional" type="warning"/>
 
 - Type: `false` or `Partial<CacheProperties<R, D>>`.
-- Default: `{}` _(Inherits from global options)_
+- Default: `{}` _(Inherits from global configuration)_
 
 ::: tip
 
-This property is optional, and if not provided, the default cache properties will be used.
+As this property is optional, when not provided, all properties will inherit from global
+configuration
 
 :::
 
@@ -79,17 +82,16 @@ value
 - Type: `boolean`
 - Default: `true`
 
-If activated, when the response is received, the `ttl` property will be inferred from the
-requests headers. As described in the MDN docs and HTML specification.
-
 ::: tip
 
-You can override the default behavior by setting the
-**[headerInterpreter](../config.md#headerinterpreter)** when creating the cached axios
-client.
+You can override the default behavior by changing the
+**[headerInterpreter](../config.md#headerinterpreter)** option.
 
 :::
 
+If activated, when the response is received, the `ttl` property will be inferred from the
+requests headers. As described in the MDN docs and HTML specification.
+
 See the actual implementation of the
 [`interpretHeader`](https://github.com/arthurfiorette/axios-cache-interceptor/blob/main/src/header/interpreter.ts)
 method for more information.
@@ -165,19 +167,19 @@ exceptions to the method rule.
 - Type: `CachePredicate<R, D>`
 - Default: `{}`
 
-An object or function that will be tested against the response to test if it can be
+An object or function that will be tested against the response to indicate if it can be
 cached.
 
 ```ts{5,8,13}
 axios.get<{ auth: { status: string } }>('url', {
   cache: {
     cachePredicate: {
       // Only cache if the response comes with a "good" status code
-      statusCheck: (status) => /* some calculation */ true,
+      statusCheck: (status) =>  true, // some calculation
 
       // Tests against any header present in the response.
       containsHeaders: {
-        'x-custom-header-3': (value) => /* some calculation */ true
+        'x-custom-header-3': (value) => true // some calculation
       },
 
       // Check custom response body
@@ -261,14 +263,18 @@ To use `true` (automatic ETag handling), `interpretHeader` option must be set to
 - Type: `boolean`
 - Default: `true`
 
-Use `If-Modified-Since` header in this request. Use a date to force a custom static value
-or true to use the last cached timestamp.
+Use
+[`If-Modified-Since`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Modified-Since)
+header in this request. Use a date to force a custom static value or true to use the last
+cached timestamp.
 
 If never cached before, the header is not set.
 
-If `interpretHeader` is set and a `Last-Modified` header is sent to us, then value from
-that header is used, otherwise cache creation timestamp will be sent in
-`If-Modified-Since`.
+If `interpretHeader` is set and a
+[`Last-Modified`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified)
+header is sent to us, then value from that header is used, otherwise cache creation
+timestamp will be sent in
+[`If-Modified-Since`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Modified-Since).
 
 ## cache.staleIfError
 
@@ -299,7 +305,7 @@ const customPredicate = (response, cache, error) => {
 };
 ```
 
-Types Explanations
+Types:
 
 - `number` -> the max time (in seconds) that the cache can be reused.
 - `boolean` -> `false` disables and `true` enables with infinite time.

docs/src/config/response-object.md

@@ -1,43 +1,35 @@
 # Response object
 
-Every response that came from our custom axios instance will have some extras properties.
+Axios cache interceptor returns a slightly changed than the original axios response.
+Containing information about the cache and other needed properties.
 
-```ts
-const response = await axios.get('https://jsonplaceholder.typicode.com/posts/1');
+## id
 
-// response.data
-// response.cached
-// response.id
-// ...
-```
+- Type: `string`
 
-Every response that came from our custom axios instance, will have some extras properties,
-that you can retrieve like that:
+The [Request ID](../guide/request-id.md) used in this request.
+
+It may have been generated by the [Key Generator](../guide/request-id.md#custom-generator)
+or a custom one provided by [`config.id`](./request-specifics.md#id)
 
 ```ts
-const result = await cache.get(/* ... */);
-const id = result['propertyName'];
+const response = await axios.get('url', { id: 'my-overridden-id' });
+
+// This request used 'my-overridden-id' and
+// not the one generated by the key generator
+response.id === 'my-overridden-id';
 ```
 
-## `cached`
+## cached
 
 - Type: `boolean`
 
-A simple boolean that tells you if this request came from the cache or through the
-network.
+A simple boolean indicating if the request returned data from the cache or from the
+network call.
 
 ::: tip
 
-This is not a boolean to check wether this request is capable of being cached or not.
+This does not indicated if the request was capable of being cached or not, as options like
+[`cache.override`](./request-specifics.md#cache-override) may have been enabled.
 
 :::
-
-## `id`
-
-- Type: `string`
-
-The resolved [request id](../guide/request-id.md). This property represents the ID used
-throughout the internal code.
-
-Depending on the [Key Generator](../guide/request-id.md#custom-generator), it can differ
-from provided example on the [Request Id](../guide/request-id.md).

docs/src/guide/storages.md

@@ -126,7 +126,7 @@ storages, you can use them as a base to also create your own.
 
 - [Node Redis v4](#node-redis-v4-example)
 - **Have another one?**
-  [Open a PR](https://github.com/arthurfiorette/axios-cache-interceptor/pulls) to add it
+- [Open a PR](https://github.com/arthurfiorette/axios-cache-interceptor/pulls) to add it
   here.
 
 ## Node Redis Example

src/cache/axios.ts

@@ -11,16 +11,40 @@ import type {
 import type { CacheInstance, CacheProperties } from './cache';
 
 /**
+ * A slightly changed than the original axios response. Containing information about the
+ * cache and other needed properties.
+ *
  * @template R The type returned by this response
  * @template D The type that the request body was
+ * @see https://axios-cache-interceptor.js.org/config/response-object
  */
 export type CacheAxiosResponse<R = any, D = any> = AxiosResponse<R, D> & {
   config: CacheRequestConfig<R, D>;
 
-  /** The id used for this request. if config specified an id, the id will be returned */
+  /**
+   * The [Request ID](https://axios-cache-interceptor.js.org/guide/request-id) used in
+   * this request.
+   *
+   * It may have been generated by the [Key
+   * Generator](https://axios-cache-interceptor.js.org/guide/request-id#custom-generator)
+   * or a custom one provided by
+   * [`config.id`](https://axios-cache-interceptor.js.org/config/request-specifics#id)
+   *
+   * @see https://axios-cache-interceptor.js.org/config/response-object#id
+   */
   id: string;
 
-  /** A simple boolean to check whether this request was cached or not */
+  /**
+   * A simple boolean indicating if the request returned data from the cache or from the
+   * network call.
+   *
+   * This does not indicated if the request was capable of being cached or not, as options
+   * like
+   * [`cache.override`](https://axios-cache-interceptor.js.org/config/request-specifics#cache-override)
+   * may have been enabled.
+   *
+   * @see https://axios-cache-interceptor.js.org/config/response-object#cached
+   */
   cached: boolean;
 };
 
@@ -32,17 +56,29 @@ export type CacheAxiosResponse<R = any, D = any> = AxiosResponse<R, D> & {
  */
 export type CacheRequestConfig<R = any, D = any> = AxiosRequestConfig<D> & {
   /**
-   * An id for this request, if this request is used in cache, only the last request made
-   * with this id will be returned.
+   * The [Request ID](https://axios-cache-interceptor.js.org/guide/request-id) used in
+   * this request.
    *
-   * @default undefined
+   * It may have been generated by the [Key
+   * Generator](https://axios-cache-interceptor.js.org/guide/request-id#custom-generator)
+   * or a custom one provided by
+   * [`config.id`](https://axios-cache-interceptor.js.org/config/request-specifics#id)
+   *
+   * @default 'auto generated by the current key generator'
+   * @see https://axios-cache-interceptor.js.org/config/response-object#id
    */
   id?: string;
 
   /**
-   * All cache options for the request.
+   * The cache option available through the request config is where all the cache
+   * customization happens.
+   *
+   * Setting the `cache` property to `false` will disable the cache for this request.
+   *
+   * This does not mean that the current cache will be excluded from the storage.
    *
-   * False means ignore everything about cache, for this request.
+   * @default 'inherits from global configuration'
+   * @see https://axios-cache-interceptor.js.org/config/response-object#cache
    */
   cache?: false | Partial<CacheProperties<R, D>>;
 };
@@ -56,9 +92,7 @@ export type InternalCacheRequestConfig<R = any, D = any> = CacheRequestConfig<R,
  * Same as the AxiosInstance but with CacheRequestConfig as a config type and
  * CacheAxiosResponse as response type.
  *
- * @see AxiosInstance
- * @see CacheRequestConfig
- * @see CacheInstance
+ * @see https://axios-cache-interceptor.js.org/guide/getting-started
  */
 export interface AxiosCacheInstance extends CacheInstance, AxiosInstance {
   // eslint-disable-next-line @typescript-eslint/no-misused-new