Descripex.Describe (descripex v0.12.0)

Progressive disclosure for Descripex-powered libraries.

Three levels of detail, each driven by a single describe function:

describe(modules)                         # Level 1: library overview
describe(modules, mod_or_short)           # Level 2: module functions
describe(modules, mod_or_short, func)     # Level 3: function detail

The first argument is always the module list. The second accepts a full module atom (MyLib.Funding), a short name string ("funding"), or the same short name as an atom (:funding). Short names are derived from the last segment of the module name, downcased and underscored.

Short names are strings, not atoms: they are labels derived from a caller-supplied module list, so interning them would grow the atom table on input this library does not control. Lookup normalizes whatever form the caller passes, so :funding and "funding" are interchangeable as arguments.

Examples

modules = [MyLib.Funding, MyLib.Risk]

Descripex.Describe.describe(modules)
# => [%{module: MyLib.Funding, short_name: "funding", ...}, ...]

Descripex.Describe.describe(modules, "funding")
# => [%{name: :annualize, arity: 2, ...}, ...]

Descripex.Describe.describe(modules, "funding", :annualize)
# => %{name: :annualize, arity: 2, params: %{...}, ...}

API Functions

Function	Arity	Description	Param Kinds
`describe`	3	Progressive disclosure — call with 1, 2, or 3 args for increasing detail.	`modules: value`, `mod_or_short: value`, `func_name: value`

Summary

Functions

describe(modules)

Progressive disclosure — call with 1, 2, or 3 args for increasing detail.

describe(modules, mod_or_short)

Return the function list for a specific module.

describe(modules, mod_or_short, func_name)

Return full detail for a specific function in a module.

Functions

describe(modules)

@spec describe([module()]) :: [map()]

Progressive disclosure — call with 1, 2, or 3 args for increasing detail.

Parameters

modules - List of module atoms to introspect (value)
mod_or_short - Full module atom, or short name as string or atom, to drill into (value)
func_name - Function name atom for Level 3 detail (value)

Returns

Level 1: [module_summary], Level 2: [function_summary], Level 3: function_detail | nil (list_or_map)

Errors

:argument_error - Raised when short name is not found or is ambiguous

# descripex:contract
%{
  params: %{
    modules: %{description: "List of module atoms to introspect", kind: :value},
    mod_or_short: %{
      description: "Full module atom, or short name as string or atom, to drill into",
      kind: :value
    },
    func_name: %{
      description: "Function name atom for Level 3 detail",
      kind: :value
    }
  },
  errors: [
    argument_error: "Raised when short name is not found or is ambiguous"
  ],
  returns: %{
    type: :list_or_map,
    description: "Level 1: [module_summary], Level 2: [function_summary], Level 3: function_detail | nil"
  }
}

describe(modules, mod_or_short)

@spec describe([module()], module() | atom() | String.t()) :: [map()]

Return the function list for a specific module.

The second argument can be a full module atom, or a short name as a string or an atom. Raises ArgumentError if the short name is not found or is ambiguous.

describe(modules, mod_or_short, func_name)

@spec describe([module()], module() | atom() | String.t(), atom()) :: map() | nil

Return full detail for a specific function in a module.

Returns nil if the function is not found in the module.