Merge pull request #8 from rustkas/General-improvements

General improvements

.github/workflows/test.yml

@@ -18,7 +18,7 @@ jobs:
 
     strategy:
       matrix:
-        otp_version: [19.3,20,21,22,23]
+        otp_version: [22,23,24,25]
         os: [ubuntu-latest]
 
     container:

.gitignore

@@ -5,4 +5,9 @@ c_src/*.o
 .eunit/
 _build
 c_src/eiconv_nif.d
-rebar3
+rebar3
+doc/*
+!doc/style.css
+!doc/overview.edoc
+.vscode
+erl_crash.dump

Makefile

@@ -21,8 +21,19 @@ dialyzer: $(REBAR)
 xref: $(REBAR)
 	$(REBAR) as test xref
 
-clean: $(REBAR)
+clean: $(REBAR) clean_doc
 	$(REBAR) clean
+
+clean_doc:
+	@rm -f doc/*.html
+	@rm -f doc/erlang.png
+	@rm -f doc/edoc-info
+
+edoc:  $(REBAR)
+	$(REBAR) edoc
+
+edoc_private:  $(REBAR)
+	$(REBAR) as edoc_private edoc
 
 ./rebar3:
 	$(ERL) -noshell -s inets -s ssl \

README.md

@@ -1,7 +1,11 @@
-# Erlang NIF wrapper for iconv
+[![Build Status][gh badge]][gh]
+[![Hex.pm version][hexpm version]][hexpm]
+[![Hex.pm Downloads][hexpm downloads]][hexpm]
+[![Hex.pm Documentation][hexdocs documentation]][hexdocs]
+[![Erlang Versions][erlang version badge]][gh]
+[![License][license]](https://www.apache.org/licenses/LICENSE-2.0)
 
-![Test](https://github.com/zotonic/eiconv/workflows/Test/badge.svg)
-[![Hex pm](http://img.shields.io/hexpm/v/eiconv.svg?style=flat)](https://hex.pm/packages/eiconv)
+# Erlang NIF wrapper for iconv
 
 An Erlang wrapper for the character set conversion utility [iconv](https://en.wikipedia.org/wiki/Iconv).
 
@@ -63,3 +67,14 @@ Wrapper provided by Maas-Maarten Zeeman and the [Zotonic](https://github.com/zot
 * [Maas-Maarten Zeeman](https://github.com/mmzeeman)
 * [Arjan Scherpenisse](https://github.com/arjan)
 * [Marc Worrell](https://github.com/mworrell)
+
+<!-- Badges -->
+[hexpm]: https://hex.pm/packages/eiconv
+[hexpm version]: https://img.shields.io/hexpm/v/eiconv.svg?style=flat-curcle "Hex version"
+[hexpm downloads]: https://img.shields.io/hexpm/dt/eiconv.svg?style=flat-curcle
+[hexdocs documentation]: https://img.shields.io/badge/hex-docs-purple.svg?style=flat-curcle
+[hexdocs]: https://hexdocs.pm/eiconv
+[gh]: https://github.com/zotonic/eiconv/actions/workflows/test.yaml
+[gh badge]: https://github.com/zotonic/eiconv/workflows/Test/badge.svg
+[erlang version badge]: https://img.shields.io/badge/Supported%20Erlang%2FOTP-22%20to%2025-blue.svg?style=flat-curcle
+[license]: https://img.shields.io/badge/License-Apache_2.0-blue.svg?logo=apache&logoColor=red "Apache 2.0"

doc/overview.edoc

@@ -0,0 +1,7 @@
+@author Zotonic Team 
+   [http://zotonic.com]
+@title iconv NIF interface 
+@doc An Erlang wrapper for the character set conversion utility 
+<abbr title="internationalization conversion">[https://en.wikipedia.org/wiki/Iconv iconv]</abbr>.
+@copyright 2011, 2012, 2013 Maas-Maarten Zeeman, Apache-2.0
+@since 2011

doc/style.css

@@ -0,0 +1,75 @@
+/* standard EDoc style sheet */
+body {
+	font-family: Verdana, Arial, Helvetica, sans-serif;
+      	margin-left: .25in;
+       	margin-right: .2in;
+       	margin-top: 0.2in;
+       	margin-bottom: 0.2in;
+       	color: #000000;
+       	background-color: #ffffff;
+}
+h1,h2 {
+ 	margin-left: -0.2in;
+}
+div.navbar {
+	background-color: #add8e6;
+	padding: 0.2em;
+}
+h2.indextitle {
+	padding: 0.4em;
+	background-color: #add8e6;
+}
+h3.function,h3.typedecl {
+	background-color: #add8e6;
+ 	padding-left: 1em;
+}
+div.spec {
+ 	margin-left: 2em;
+
+	background-color: #eeeeee;
+}
+a.module {
+	text-decoration:none
+}
+a.module:hover {
+	background-color: #eeeeee;
+}
+ul.definitions {
+	list-style-type: none;
+}
+ul.index {
+	list-style-type: none;
+	background-color: #eeeeee;
+}
+
+/*
+ * Minor style tweaks
+ */
+ul {
+	list-style-type: square;
+}
+table {
+	border-collapse: collapse;
+}
+td {
+	padding: 3px;
+	vertical-align: middle;
+}
+
+/*
+Tune styles
+*/
+
+table[summary="navigation bar"] {
+	background-image: url('http://zotonic.com/lib/images/logo.png');
+	background-repeat: no-repeat;
+	background-position: center;
+}
+
+code, p>tt, a>tt {
+	font-size: 1.2em;
+}
+
+p {
+	line-height: 1.5;
+}

rebar.config

@@ -45,5 +45,12 @@
                 ]
             }
         ]}
+    ]},
+    {edoc_private, [
+        {edoc_opts, [{private, true}]}
     ]}
 ]}.
+
+{edoc_opts, [
+    {preprocess, true}, {stylesheet, "style.css"}
+]}.

src/eiconv.erl

@@ -1,16 +1,37 @@
-% Copyright 2011, 2012, 2013 Maas-Maarten Zeeman
-%
-% Licensed under the Apache License, Version 2.0 (the "License");
-% you may not use this file except in compliance with the License.
-% You may obtain a copy of the License at
-% 
-%     http://www.apache.org/licenses/LICENSE-2.0
-% 
-% Unless required by applicable law or agreed to in writing, software
-% distributed under the License is distributed on an "AS IS" BASIS,
-% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-% See the License for the specific language governing permissions and
-% limitations under the License.
+%%% Copyright 2011, 2012, 2013 Maas-Maarten Zeeman
+%%%
+%%% Licensed under the Apache License, Version 2.0 (the "License");
+%%% you may not use this file except in compliance with the License.
+%%% You may obtain a copy of the License at
+%%% 
+%%%     http://www.apache.org/licenses/LICENSE-2.0
+%%% 
+%%% Unless required by applicable law or agreed to in writing, software
+%%% distributed under the License is distributed on an "AS IS" BASIS,
+%%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+%%% See the License for the specific language governing permissions and
+%%% limitations under the License.
+%%%
+%%% @author Maas-Maarten Zeeman <mmzeeman@xs4all.nl>
+%%% @doc eiconv module.
+%%%
+%%% <h3>There two type of APIs:</h3>
+%%% <ul>
+%%%   <li><b>Easy API one shot convert API:</b>
+%%%     <ul>
+%%%       <li>{@link convert/2}</li>
+%%%       <li>{@link convert/3}</li>
+%%%     </ul>
+%%%   </li>
+%%%   <li><b>Old iconv compatible API:</b>
+%%%     <ul>
+%%%       <li>{@link open/2}</li>
+%%%       <li>{@link conv/2}</li>
+%%%       <li>{@link conv/3}</li>
+%%%       <li>{@link close/1}</li>
+%%%     </ul>
+%%%   </li>
+%%% </ul>
 
 -module(eiconv).
 -author("Maas-Maarten Zeeman <mmzeeman@xs4all.nl>").
@@ -28,8 +49,9 @@
 
 -on_load(init/0).
 
-% @doc Load the nif
-%
+%% @private
+%% @doc Load the <abbr title="native implementation of a function">NIF</abbr>
+
 init() ->
     NifName = "eiconv_nif",
     NifFileName = case code:priv_dir(eiconv) of
@@ -39,29 +61,32 @@ init() ->
 
     ok = erlang:load_nif(NifFileName, 0).
 
-% @doc Open a new encoder which can be used to convert text from FromCode into ToCode.
-%
+%% @doc Open a new encoder which can be used to convert text from `FromCode' into `ToCode'.
+
 open(_ToCode, _FromCode) ->
     erlang:nif_error(nif_library_not_loaded).
 
-% @doc Convert a chunk, returns {done, ConvertedBytes} } | {more, Converted}
-%
+%% @private
+%% @doc Convert a chunk, returns `{done, ConvertedBytes} } | {more, Converted}'
+
 chunk(_Cd, _Input) ->
     erlang:nif_error(nif_library_not_loaded).
 
-% @doc Reset the cd structure, returns ok | {rest, LeftOverBytes}
-%
+%% @private
+%% @doc Reset the cd structure, 
+%% @returns `ok | {rest, LeftOverBytes}'
+
 finalize(_Cd) ->
     erlang:nif_error(nif_library_not_loaded).
 
-% @doc Convert Input into the requested encoding.
-%
+%% @doc Convert Input into the requested encoding.
+
 conv(Cd, Input) ->
     conv(Cd, Input, ?DEFAULT_CHUNK_SIZE).
 
-% @doc Convert input. The input will first be split into 
-% chunks of ChunkSize before being converted by the nif.
-%
+%% @doc Convert input. The input will first be split into 
+%% chunks of `ChunkSize' before being converted by the nif.
+
 conv(Cd, Input, ChunkSize) ->
     Chunks = split_input(ChunkSize, Input),
     case conv1(Cd, Chunks, []) of
@@ -88,18 +113,30 @@ conv1(Cd, [H|T], Acc) ->
             conv1(Cd, T, [Result | Acc])
     end.
 
-% @doc Close the encoder - dummy function, close will be done by the garbage collector.
-%
+%% @doc Close the encoder - dummy function, close will be done by the garbage collector.
+
 close(_Cd) ->
     ok.
 
-% @doc Convert input FromEncoding to utf-8
-%
+%% @doc Convert input `FromEncoding' to `utf-8'
+%% @equiv convert(FromEncoding, "utf-8", Input)
+
+-spec convert(FromEncoding, Input) -> Result when
+    FromEncoding :: string(), 
+    Input :: string(),
+    Result :: {ok, binary()} | {error, Error},
+    Error :: term().
 convert(FromEncoding, Input) ->
     convert(FromEncoding, "utf-8", Input).
 
-% @doc Convert input which is in FromEncoding to ToEncoding.
-%
+%% @doc Convert `Input' which is in `FromEncoding' to `ToEncoding'.
+
+-spec convert(FromEncoding, ToEncoding, Input) -> Result when
+    FromEncoding :: string(), 
+    ToEncoding :: string(), 
+    Input :: string(),
+    Result :: {ok, binary()} | {error, Error},
+    Error :: term().
 convert(FromEncoding, ToEncoding, Input) ->
     case open(ToEncoding, FromEncoding) of
         {ok, Cd} ->

src/iconv.erl

@@ -1,18 +1,20 @@
-% Copyright 2011, 2012, 2013 Maas-Maarten Zeeman
-%
-% Licensed under the Apache License, Version 2.0 (the "License");
-% you may not use this file except in compliance with the License.
-% You may obtain a copy of the License at
-%
-%     http://www.apache.org/licenses/LICENSE-2.0
-%
-% Unless required by applicable law or agreed to in writing, software
-% distributed under the License is distributed on an "AS IS" BASIS,
-% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-% See the License for the specific language governing permissions and
-% limitations under the License.
-
-% drop in replacement module.
+%%% Copyright 2011, 2012, 2013 Maas-Maarten Zeeman
+%%%
+%%% Licensed under the Apache License, Version 2.0 (the "License");
+%%% you may not use this file except in compliance with the License.
+%%% You may obtain a copy of the License at
+%%%
+%%%     http://www.apache.org/licenses/LICENSE-2.0
+%%%
+%%% Unless required by applicable law or agreed to in writing, software
+%%% distributed under the License is distributed on an "AS IS" BASIS,
+%%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+%%% See the License for the specific language governing permissions and
+%%% limitations under the License.
+%%%
+%%% @author Maas-Maarten Zeeman <mmzeeman@xs4all.nl>
+%%% @doc drop in replacement module.
+%%%
 
 -module(iconv).
 -author("Maas-Maarten Zeeman <mmzeeman@xs4all.nl>").