From 381bef40bb8fea6360136555651cebefc4daaf4c Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Mon, 7 Mar 2011 15:43:52 +0100 Subject: Clean up edoc_lib(3) The edoc_lib module is meant to be private, but since it is referred to from other man pages it has been included in the OTP documentation. This change makes all functions private except those referred to from other pages. --- lib/edoc/src/edoc_lib.erl | 43 +++++++++++++++++++++++++++++++++++++++---- 1 file changed, 39 insertions(+), 4 deletions(-) (limited to 'lib/edoc/src/edoc_lib.erl') diff --git a/lib/edoc/src/edoc_lib.erl b/lib/edoc/src/edoc_lib.erl index c1f95a7a67..6705ccd356 100644 --- a/lib/edoc/src/edoc_lib.erl +++ b/lib/edoc/src/edoc_lib.erl @@ -16,7 +16,6 @@ %% %% $Id$ %% -%% @private %% @copyright 2001-2003 Richard Carlsson %% @author Richard Carlsson %% @see edoc @@ -49,14 +48,17 @@ %% --------------------------------------------------------------------- %% List and string utilities +%% @private timestr({H,M,Sec}) -> lists:flatten(io_lib:fwrite("~2.2.0w:~2.2.0w:~2.2.0w",[H,M,Sec])). +%% @private datestr({Y,M,D}) -> Ms = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"], lists:flatten(io_lib:fwrite("~s ~w ~w",[lists:nth(M, Ms),D,Y])). +%% @private count(X, Xs) -> count(X, Xs, 0). @@ -67,6 +69,7 @@ count(X, [_ | Xs], N) -> count(_X, [], N) -> N. +%% @private lines(Cs) -> lines(Cs, [], []). @@ -77,6 +80,7 @@ lines([C | Cs], As, Ls) -> lines([], As, Ls) -> lists:reverse([lists:reverse(As) | Ls]). +%% @private split_at(Cs, K) -> split_at(Cs, K, []). @@ -87,6 +91,7 @@ split_at([C | Cs], K, As) -> split_at([], _K, As) -> {lists:reverse(As), []}. +%% @private split_at_stop(Cs) -> split_at_stop(Cs, []). @@ -103,6 +108,7 @@ split_at_stop([C | Cs], As) -> split_at_stop([], As) -> {lists:reverse(As), []}. +%% @private split_at_space(Cs) -> split_at_space(Cs, []). @@ -117,17 +123,20 @@ split_at_space([C | Cs], As) -> split_at_space([], As) -> {lists:reverse(As), []}. +%% @private is_space([$\s | Cs]) -> is_space(Cs); is_space([$\t | Cs]) -> is_space(Cs); is_space([$\n | Cs]) -> is_space(Cs); is_space([_C | _Cs]) -> false; is_space([]) -> true. +%% @private strip_space([$\s | Cs]) -> strip_space(Cs); strip_space([$\t | Cs]) -> strip_space(Cs); strip_space([$\n | Cs]) -> strip_space(Cs); strip_space(Cs) -> Cs. +%% @private segment(Es, N) -> segment(Es, [], [], 0, N). @@ -140,6 +149,7 @@ segment([], [], Cs, _N, _M) -> segment([], As, Cs, _N, _M) -> lists:reverse([lists:reverse(As) | Cs]). +%% @private transpose([]) -> []; transpose([[] | Xss]) -> transpose(Xss); transpose([[X | Xs] | Xss]) -> @@ -151,6 +161,7 @@ transpose([[X | Xs] | Xss]) -> %% end of the summary sentence only if it is also the last segment in %% the list, or is followed by a 'p' or 'br' ("whitespace") element. +%% @private get_first_sentence([#xmlElement{name = p, content = Es} | _]) -> %% Descend into initial paragraph. get_first_sentence_1(Es); @@ -230,6 +241,7 @@ end_of_sentence_1(_, false, _) -> %% Names must begin with a lowercase letter and contain only %% alphanumerics and underscores. +%% @private is_name([C | Cs]) when C >= $a, C =< $z -> is_name_1(Cs); is_name([C | Cs]) when C >= $\337, C =< $\377, C =/= $\367 -> @@ -252,6 +264,7 @@ is_name_1(_) -> false. to_atom(A) when is_atom(A) -> A; to_atom(S) when is_list(S) -> list_to_atom(S). +%% @private unique([X | Xs]) -> [X | unique(Xs, X)]; unique([]) -> []. @@ -267,6 +280,7 @@ unique([], _) -> []. %% content of `@equiv' %% tags, and strings denoting file names, e.g. in @headerfile. Also used %% by {@link edoc_run}. +%% @private parse_expr(S, L) -> case erl_scan:string(S ++ ".", L) of @@ -287,10 +301,11 @@ parse_expr(S, L) -> %% @doc EDoc "contact information" parsing. This is the type of the %% content in e.g. %% `@author' tags. +%% @private -%% @type info() = #info{name = string(), -%% email = string(), -%% uri = string()} +%% % @type info() = #info{name = string(), +%% % email = string(), +%% % uri = string()} -record(info, {name = "" :: string(), email = "" :: string(), @@ -367,6 +382,7 @@ strip_and_reverse(As) -> %% %% TODO: general utf-8 encoding for all of Unicode (0-16#10ffff) +%% @private escape_uri([C | Cs]) when C >= $a, C =< $z -> [C | escape_uri(Cs)]; escape_uri([C | Cs]) when C >= $A, C =< $Z -> @@ -409,6 +425,7 @@ hex_octet(N) -> %% Please note that URI are *not* file names. Don't use the stdlib %% 'filename' module for operations on (any parts of) URI. +%% @private join_uri(Base, "") -> Base; join_uri("", Path) -> @@ -418,6 +435,7 @@ join_uri(Base, Path) -> %% Check for relative URI; "network paths" ("//...") not included! +%% @private is_relative_uri([$: | _]) -> false; is_relative_uri([$/, $/ | _]) -> @@ -433,6 +451,7 @@ is_relative_uri([_ | Cs]) -> is_relative_uri([]) -> true. +%% @private uri_get("file:///" ++ Path) -> uri_get_file(Path); uri_get("file://localhost/" ++ Path) -> @@ -532,6 +551,7 @@ uri_get_ftp(URI) -> Msg = io_lib:format("cannot access ftp scheme yet: '~s'.", [URI]), {error, Msg}. +%% @private to_label([$\s | Cs]) -> to_label(Cs); to_label([$\t | Cs]) -> @@ -564,6 +584,7 @@ to_label_2(Cs) -> %% --------------------------------------------------------------------- %% Files +%% @private filename([C | T]) when is_integer(C), C > 0 -> [C | filename(T)]; filename([H|T]) -> @@ -576,6 +597,7 @@ filename(N) -> report("bad filename: `~P'.", [N, 25]), exit(error). +%% @private copy_file(From, To) -> case file:copy(From, To) of {ok, _} -> ok; @@ -600,6 +622,7 @@ list_dir(Dir, Error) -> F("could not read directory '~s': ~s.", [filename(Dir), R1]) end. +%% @private simplify_path(P) -> case filename:basename(P) of "." -> @@ -636,6 +659,7 @@ simplify_path(P) -> %% exit(error) %% end. +%% @private try_subdir(Dir, Subdir) -> D = filename:join(Dir, Subdir), case filelib:is_dir(D) of @@ -648,6 +672,7 @@ try_subdir(Dir, Subdir) -> %% %% @doc Write the given `Text' to the file named by `Name' in directory %% `Dir'. If the target directory does not exist, it will be created. +%% @private write_file(Text, Dir, Name) -> write_file(Text, Dir, Name, ''). @@ -657,6 +682,7 @@ write_file(Text, Dir, Name) -> %% Name::edoc:filename(), Package::atom()|string()) -> ok %% @doc Like {@link write_file/3}, but adds path components to the target %% directory corresponding to the specified package. +%% @private write_file(Text, Dir, Name, Package) -> Dir1 = filename:join([Dir | packages:split(Package)]), @@ -672,6 +698,7 @@ write_file(Text, Dir, Name, Package) -> exit(error) end. +%% @private write_info_file(App, Packages, Modules, Dir) -> Ts = [{packages, Packages}, {modules, Modules}], @@ -703,6 +730,7 @@ info_file_data(Ts) -> %% Local file access - don't complain if file does not exist. +%% @private read_info_file(Dir) -> File = filename:join(Dir, ?INFO_FILE), case filelib:is_file(File) of @@ -769,11 +797,13 @@ parse_terms_1([], _As, _Vs) -> %% --------------------------------------------------------------------- %% Source files and packages +%% @private find_sources(Path, Opts) -> find_sources(Path, "", Opts). %% @doc See {@link edoc:run/3} for a description of the options %% `subpackages', `source_suffix' and `exclude_packages'. +%% @private %% NEW-OPTIONS: subpackages, source_suffix, exclude_packages %% DEFER-OPTIONS: edoc:run/3 @@ -827,6 +857,7 @@ is_package_dir(Name, Dir) -> is_name(filename:rootname(filename:basename(Name))) andalso filelib:is_dir(filename:join(Dir, Name)). +%% @private find_file([P | Ps], Pkg, Name) -> Dir = filename:join(P, filename:join(packages:split(Pkg))), File = filename:join(Dir, Name), @@ -839,6 +870,7 @@ find_file([P | Ps], Pkg, Name) -> find_file([], _Pkg, _Name) -> "". +%% @private find_doc_dirs() -> find_doc_dirs(code:get_path()). @@ -904,6 +936,7 @@ add_new(K, V, D) -> %% @spec (Options::proplist()) -> edoc_env() %% @equiv get_doc_env([], [], [], Opts) +%% @private get_doc_env(Opts) -> get_doc_env([], [], [], Opts). @@ -952,6 +985,7 @@ get_doc_env(App, Packages, Modules, Opts) -> %% NEW-OPTIONS: doclet %% DEFER-OPTIONS: edoc:run/3 +%% @private run_doclet(Fun, Opts) -> run_plugin(doclet, ?DEFAULT_DOCLET, Fun, Opts). @@ -961,6 +995,7 @@ run_doclet(Fun, Opts) -> %% NEW-OPTIONS: layout %% DEFER-OPTIONS: edoc:layout/2 +%% @private run_layout(Fun, Opts) -> run_plugin(layout, ?DEFAULT_LAYOUT, Fun, Opts). -- cgit v1.2.3 From 8052b98f596db048467c0c57cbaac1d3a27687ad Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Tue, 22 Jun 2010 09:42:44 +0200 Subject: Make Erlang specifications and types available in EDoc It is now possible to use Erlang specifications and types in EDoc documentation. Erlang specifications and types will be used unless there is also a function specification (@spec) or a type alias (@type) with the same name. In the current implementation the placement of -spec matters: it should be placed where the @spec would otherwise have been placed. Not all Erlang types are included in the documentation, but only those exported by some export_type declaration or used by some documented Erlang specification (-spec). There is currently no support for overloaded Erlang specifications. The syntax definitions of EDoc have been augmented to cope with most of the Erlang types. (But we recommend that Erlang types should be used instead.) edoc:read_source() takes one new option, report_missing_types. edoc_layout:module() takes one new option, pretty_printer. --- lib/edoc/src/edoc_lib.erl | 1 + 1 file changed, 1 insertion(+) (limited to 'lib/edoc/src/edoc_lib.erl') diff --git a/lib/edoc/src/edoc_lib.erl b/lib/edoc/src/edoc_lib.erl index 6705ccd356..585e30a2d2 100644 --- a/lib/edoc/src/edoc_lib.erl +++ b/lib/edoc/src/edoc_lib.erl @@ -947,6 +947,7 @@ get_doc_env(Opts) -> %% Modules = [atom()] %% proplist() = [term()] %% +%% @type proplist() = proplists:property(). %% @type edoc_env(). Environment information needed by EDoc for %% generating references. The data representation is not documented. %% -- cgit v1.2.3