diff options
Diffstat (limited to 'lib/edoc/src/edoc_lib.erl')
| -rw-r--r-- | lib/edoc/src/edoc_lib.erl | 84 |
1 files changed, 63 insertions, 21 deletions
diff --git a/lib/edoc/src/edoc_lib.erl b/lib/edoc/src/edoc_lib.erl index 47e61f7932..7fd8358add 100644 --- a/lib/edoc/src/edoc_lib.erl +++ b/lib/edoc/src/edoc_lib.erl @@ -14,11 +14,8 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% $Id$ -%% -%% @private %% @copyright 2001-2003 Richard Carlsson -%% @author Richard Carlsson <[email protected]> +%% @author Richard Carlsson <[email protected]> %% @see edoc %% @end %% ===================================================================== @@ -41,7 +38,7 @@ -import(edoc_report, [report/2, warning/2]). -include("edoc.hrl"). --include("xmerl.hrl"). +-include_lib("xmerl/include/xmerl.hrl"). -define(FILE_BASE, "/"). @@ -49,14 +46,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 +67,7 @@ count(X, [_ | Xs], N) -> count(_X, [], N) -> N. +%% @private lines(Cs) -> lines(Cs, [], []). @@ -77,6 +78,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 +89,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 +106,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 +121,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 +147,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 +159,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 +239,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 +262,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 +278,7 @@ unique([], _) -> []. %% content of <a href="overview-summary.html#ftag-equiv">`@equiv'</a> %% 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,12 +299,15 @@ parse_expr(S, L) -> %% @doc EDoc "contact information" parsing. This is the type of the %% content in e.g. %% <a href="overview-summary.html#mtag-author">`@author'</a> tags. +%% @private -%% @type info() = #info{name = string(), -%% mail = string(), -%% uri = string()} +%% % @type info() = #info{name = string(), +%% % email = string(), +%% % uri = string()} --record(info, {name = "", email = "", uri = ""}). +-record(info, {name = "" :: string(), + email = "" :: string(), + uri = "" :: string()}). parse_contact(S, L) -> I = scan_name(S, L, #info{}, []), @@ -365,6 +380,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 -> @@ -387,8 +403,13 @@ escape_uri([C | Cs]) -> escape_uri([]) -> []. -escape_byte(C) -> - "%" ++ hex_octet(C). +escape_byte(C) when C >= 0, C =< 255 -> + [$%, hex_digit(C bsr 4), hex_digit(C band 15)]. + +hex_digit(N) when N >= 0, N =< 9 -> + N + $0; +hex_digit(N) when N > 9, N =< 15 -> + N + $a - 10. % utf8([C | Cs]) when C > 16#7f -> % [((C band 16#c0) bsr 6) + 16#c0, C band 16#3f ++ 16#80 | utf8(Cs)]; @@ -397,16 +418,10 @@ escape_byte(C) -> % utf8([]) -> % []. -hex_octet(N) when N =< 9 -> - [$0 + N]; -hex_octet(N) when N > 15 -> - hex_octet(N bsr 4) ++ hex_octet(N band 15); -hex_octet(N) -> - [N - 10 + $a]. - %% 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) -> @@ -416,6 +431,7 @@ join_uri(Base, Path) -> %% Check for relative URI; "network paths" ("//...") not included! +%% @private is_relative_uri([$: | _]) -> false; is_relative_uri([$/, $/ | _]) -> @@ -431,6 +447,7 @@ is_relative_uri([_ | Cs]) -> is_relative_uri([]) -> true. +%% @private uri_get("file:///" ++ Path) -> uri_get_file(Path); uri_get("file://localhost/" ++ Path) -> @@ -472,8 +489,8 @@ uri_get_file(File0) -> uri_get_http(URI) -> %% Try using option full_result=false - case catch {ok, http:request(get, {URI,[]}, [], - [{full_result, false}])} of + case catch {ok, httpc:request(get, {URI,[]}, [], + [{full_result, false}])} of {'EXIT', _} -> uri_get_http_r10(URI); Result -> @@ -482,7 +499,7 @@ uri_get_http(URI) -> uri_get_http_r10(URI) -> %% Try most general form of request - Result = (catch {ok, http:request(get, {URI,[]}, [], [])}), + Result = (catch {ok, httpc:request(get, {URI,[]}, [], [])}), uri_get_http_1(Result, URI). uri_get_http_1(Result, URI) -> @@ -530,6 +547,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]) -> @@ -562,6 +580,7 @@ to_label_2(Cs) -> %% --------------------------------------------------------------------- %% Files +%% @private filename([C | T]) when is_integer(C), C > 0 -> [C | filename(T)]; filename([H|T]) -> @@ -574,6 +593,7 @@ filename(N) -> report("bad filename: `~P'.", [N, 25]), exit(error). +%% @private copy_file(From, To) -> case file:copy(From, To) of {ok, _} -> ok; @@ -598,6 +618,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 "." -> @@ -634,6 +655,7 @@ simplify_path(P) -> %% exit(error) %% end. +%% @private try_subdir(Dir, Subdir) -> D = filename:join(Dir, Subdir), case filelib:is_dir(D) of @@ -646,6 +668,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, ''). @@ -655,6 +678,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)]), @@ -670,6 +694,7 @@ write_file(Text, Dir, Name, Package) -> exit(error) end. +%% @private write_info_file(App, Packages, Modules, Dir) -> Ts = [{packages, Packages}, {modules, Modules}], @@ -701,6 +726,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 @@ -767,11 +793,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 @@ -825,6 +853,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), @@ -837,6 +866,7 @@ find_file([P | Ps], Pkg, Name) -> find_file([], _Pkg, _Name) -> "". +%% @private find_doc_dirs() -> find_doc_dirs(code:get_path()). @@ -902,6 +932,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). @@ -912,6 +943,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. %% @@ -950,6 +982,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). @@ -959,6 +992,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). @@ -988,6 +1022,14 @@ get_plugin(Key, Default, Opts) -> %% --------------------------------------------------------------------- %% Error handling +-type line() :: erl_scan:line(). +-type err() :: 'eof' + | {'missing', char()} + | {line(), atom(), string()} + | string(). + +-spec throw_error(err(), line()) -> no_return(). + throw_error({missing, C}, L) -> throw_error({"missing '~c'.", [C]}, L); throw_error(eof, L) -> |