-
-
Notifications
You must be signed in to change notification settings - Fork 3
/
docs.ex
132 lines (108 loc) · 3.34 KB
/
docs.ex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
defmodule Skogsra.Docs do
@moduledoc """
This module defines the documentation generators.
"""
alias Skogsra.Env
@typedoc """
Custom docs.
"""
@type docs :: nil | false | binary()
@typedoc """
Function name.
"""
@type function_name :: atom()
@doc """
Generates docs for a variable given its `module`, `function_name`,
`app_name`, `keys` to find it, `options` and custom `docs`.
"""
@spec gen_full_docs(
module(),
function_name(),
Env.app_name(),
Env.keys(),
Env.options(),
docs()
) :: binary()
def gen_full_docs(module, function_name, app_name, keys, options, docs)
def gen_full_docs(_, _, _, _, _, false), do: false
def gen_full_docs(module, function_name, app_name, keys, options, docs) do
if Application.get_env(:skogsra, :generate_docs, true) do
do_gen_full_docs(module, function_name, app_name, keys, options, docs)
else
"#{insert_custom_docs(docs)}"
end
end
defp do_gen_full_docs(module, function_name, app_name, keys, options, docs) do
module = Macro.to_string(module)
env = Env.new(nil, app_name, keys, options)
"""
#{insert_custom_docs(docs)}
Calling `#{module}.#{function_name}()` will ensure the following:
- Binding order: #{inspect(Env.binding_order(env))}
- OS environment variable: #{inspect(Env.os_env(env))}
- Type: #{inspect(Env.type(env))}
- Default: #{inspect(Env.default(env))}
- Required: #{inspect(Env.required?(env))}
- Cached: #{inspect(Env.cached?(env))}
"""
end
@doc """
Generates short docs for a variable given its `module`, `function_name`,
and custom `docs`.
"""
@spec gen_short_docs(
module(),
function_name(),
docs()
) :: binary()
def gen_short_docs(module, function_name, docs)
def gen_short_docs(_, _, false), do: false
def gen_short_docs(module, function_name, docs) do
module = Macro.to_string(module)
"""
#{insert_custom_docs(docs)}
Bang version of `#{module}.#{function_name}/0` (fails on error). Optionally,
receives the `namespace` for the variable.
"""
end
@doc """
Generates reload docs for a variable given its `module` and `function_name`.
"""
@spec gen_reload_docs(
module(),
function_name(),
docs()
) :: binary()
def gen_reload_docs(module, function_name, docs)
def gen_reload_docs(_, _, false), do: false
def gen_reload_docs(module, function_name, _) do
module = Macro.to_string(module)
"""
Reloads the value for `#{module}.#{function_name}/0`. Optionally, receives
the `namespace` for the variable.
"""
end
@doc """
Generates put docs for a variable given its `module` and `function_name`.
"""
@spec gen_put_docs(
module(),
function_name(),
docs()
) :: binary()
def gen_put_docs(module, function_name, docs)
def gen_put_docs(_, _, false), do: false
def gen_put_docs(module, function_name, _) do
module = Macro.to_string(module)
"""
Puts the `value` to `#{module}.#{function_name}/0`. Optionally, receives
the `namespace`.
"""
end
#########
# Helpers
@doc false
@spec insert_custom_docs(docs()) :: binary()
def insert_custom_docs(nil), do: "Use `@envdoc` to document this variable"
def insert_custom_docs(docs), do: docs
end