GithubHelp home page GithubHelp logo

stolen / autohelp Goto Github PK

View Code? Open in Web Editor NEW
35.0 35.0 5.0 306 KB

Parse_transform for erlang which adds functions help/{0,1,2} showing edoc information about module and exported functions.

License: MIT License

Erlang 100.00%

autohelp's People

Contributors

blt avatar stolen avatar

Stargazers

avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar

Watchers

avatar avatar avatar

Forkers

zavr marutha alepharchives poisonpill blt

autohelp's Issues

Autohelp does not instruct edoc to include header files.

After instructing edoc to do preprocessing any files that include headers now crash the autohelp build. I've showcased the bug in a small project here From my own system:

> yes | rm -rf deps && ./rebar clean && ./rebar get-deps && ./rebar compile
==> parse_fight (clean)
==> parse_fight (get-deps)
Pulling autohelp from {git,"git://github.com/stolen/autohelp.git",
                           {tag,"198a908d6fca517fd9da8c9a2335fd28baaaef4b"}}
Cloning into 'autohelp'...
Pulling bson from {git,"git://github.com/mongodb/bson-erlang.git",
                       {tag,"17373ef4"}}
Cloning into 'bson'...
Pulling mongodb from {git,"git://github.com/mongodb/mongodb-erlang.git",
                          {tag,"bc41adb0"}}
Cloning into 'mongodb'...
==> autohelp (get-deps)
==> bson (get-deps)
==> mongodb (get-deps)
==> autohelp (compile)
Compiled src/autohelp.erl
Compiled src/autohelp_lib.erl
Compiled src/autohelp_demo.erl
==> bson (compile)
src/bson_binary.erl: at line 6: can't find include file "bson_binary.hrl"
autohelp: edoc:get_doc crashed with exit:error on src/bson_binary.erl
autohelp WARNING: cannot retrieve documentation from src/bson_binary.erl. Run edoc:get_doc("src/bson_binary.erl") manually to investigate problem
Compiled src/bson_binary.erl
Compiled src/bson_tests.erl
Compiled src/bson.erl
==> mongodb (compile)
Compiled src/resource_pool.erl
Compiled src/mongodb_app.erl
Compiled src/mvar.erl
Compiled src/mongo_query.erl
Compiled src/mongo_replset.erl
Compiled src/mongodb_tests.erl
Compiled src/mongo_protocol.erl
Compiled src/mongo_cursor.erl
Compiled src/mongo_connect.erl
Compiled src/mongo.erl
==> parse_fight (compile)
Compiled src/behave.erl
src/db_wrapper.erl: at line 2: can't find include lib "include/fight.hrl"
autohelp: edoc:get_doc crashed with exit:error on src/db_wrapper.erl
autohelp WARNING: cannot retrieve documentation from src/db_wrapper.erl. Run edoc:get_doc("src/db_wrapper.erl") manually to investigate problem
Compiled src/parse_fight_sup.erl
Compiled src/parse_fight_app.erl
Compiled src/db_wrapper.erl

I note that the edoc manpage for edoc:read_source/2 does discuss setting paths for include files.

Autohelp fails to annotate behaviour only modules.

I've reproduced the problem in a small project here. On my system:

> yes | rm -rf deps && ./rebar clean && ./rebar get-deps && ./rebar compile
==> parse_fight (clean)
==> parse_fight (get-deps)
Pulling autohelp from {git,"git://github.com/stolen/autohelp.git",
                           {tag,"a6a688a11c3e6923cb4ff7be7b06b349e3ed2cf4"}}
Cloning into 'autohelp'...
Pulling bson from {git,"git://github.com/mongodb/bson-erlang.git",
                       {tag,"17373ef4"}}
Cloning into 'bson'...
Pulling mongodb from {git,"git://github.com/mongodb/mongodb-erlang.git",
                          {tag,"bc41adb0"}}
Cloning into 'mongodb'...
==> autohelp (get-deps)
==> bson (get-deps)
==> mongodb (get-deps)
==> autohelp (compile)
Compiled src/autohelp.erl
Compiled src/autohelp_lib.erl
Compiled src/autohelp_demo.erl
==> bson (compile)
Compiled src/bson_tests.erl
Compiled src/bson.erl
Compiled src/bson_binary.erl
==> mongodb (compile)
Compiled src/resource_pool.erl
Compiled src/mvar.erl
Compiled src/mongodb_app.erl
Compiled src/mongo_query.erl
Compiled src/mongo_replset.erl
Compiled src/mongo_protocol.erl
Compiled src/mongodb_tests.erl
Compiled src/mongo_cursor.erl
Compiled src/mongo_connect.erl
Compiled src/mongo.erl
==> parse_fight (compile)
src/behave.erl:0: attribute 'export' after function definitions
src/behave.erl:0: Warning: function '__autohelp_fun_desc'/0 is unused
src/behave.erl:0: Warning: function '__autohelp_pad_text_left'/2 is unused
src/behave.erl:0: Warning: function help/0 is unused
src/behave.erl:0: Warning: function help/1 is unused
src/behave.erl:0: Warning: function help/2 is unused
ERROR: compile failed while processing /Users/blt/projects/com/rackspace/parse_fight: rebar_abort

Autohelp does not seem to pick up documentation changes.

This one is somewhat difficult to reproduce. I've updated parse_fight to showcase the issue. If I compile a project, then change the documentation and recompile the first version of the documentation is returned by help. On my own system, I've compiled apps/parse_fight/src/db_wrapper.erl with no inline documentation. The current commit contains edocs.

> ./rebar clean && ./rebar compile
==> autohelp (clean)
==> bson (clean)
==> mongodb (clean)
==> parse_fight (clean)
==> parse_fight (clean)
==> autohelp (compile)
Compiled src/autohelp.erl
Compiled src/autohelp_lib.erl
Compiled src/autohelp_demo.erl
==> bson (compile)
Compiled src/bson_tests.erl
Compiled src/bson.erl
Compiled src/bson_binary.erl
==> mongodb (compile)
Compiled src/resource_pool.erl
Compiled src/mvar.erl
Compiled src/mongodb_app.erl
Compiled src/mongo_query.erl
Compiled src/mongo_replset.erl
Compiled src/mongodb_tests.erl
Compiled src/mongo_protocol.erl
Compiled src/mongo_cursor.erl
Compiled src/mongo_connect.erl
Compiled src/mongo.erl
==> parse_fight (compile)
Compiled src/behave.erl
Compiled src/parse_fight_sup.erl
Compiled src/parse_fight_app.erl
Compiled src/db_wrapper.erl
==> parse_fight (compile)

> erl -boot start_sasl -pa deps/*/ebin -pa apps/*/ebin -s parse_fight_app
Erlang R15B02 (erts-5.9.2) [source] [64-bit] [smp:8:8] [async-threads:0] [hipe] [kernel-poll:false]


=PROGRESS REPORT==== 4-Feb-2013::12:10:36 ===
          supervisor: {local,sasl_safe_sup}
             started: [{pid,<0.34.0>},
                       {name,alarm_handler},
                       {mfargs,{alarm_handler,start_link,[]}},
                       {restart_type,permanent},
                       {shutdown,2000},
                       {child_type,worker}]

=PROGRESS REPORT==== 4-Feb-2013::12:10:36 ===
          supervisor: {local,sasl_safe_sup}
             started: [{pid,<0.35.0>},
                       {name,overload},
                       {mfargs,{overload,start_link,[]}},
                       {restart_type,permanent},
                       {shutdown,2000},
                       {child_type,worker}]

=PROGRESS REPORT==== 4-Feb-2013::12:10:36 ===
          supervisor: {local,sasl_sup}
             started: [{pid,<0.33.0>},
                       {name,sasl_safe_sup},
                       {mfargs,
                           {supervisor,start_link,
                               [{local,sasl_safe_sup},sasl,safe]}},
                       {restart_type,permanent},
                       {shutdown,infinity},
                       {child_type,supervisor}]

=PROGRESS REPORT==== 4-Feb-2013::12:10:36 ===
          supervisor: {local,sasl_sup}
             started: [{pid,<0.36.0>},
                       {name,release_handler},
                       {mfargs,{release_handler,start_link,[]}},
                       {restart_type,permanent},
                       {shutdown,2000},
                       {child_type,worker}]

=PROGRESS REPORT==== 4-Feb-2013::12:10:36 ===
         application: sasl
          started_at: nonode@nohost
Eshell V5.9.2  (abort with ^G)
1> db_wrapper:help(find, 2).
    find(Collection, Selector)

ok

The documentation should be that as seen here.

Enabling autohelp causes a syntax error in build.

I've found that enabling build-wide autohelp causes a syntax error. I've reproduced the problem in parse_fight. To reproduce, from the root of parse_fight:

> ./rebar get-deps
> ./rebar compile

On my system the result is:

==> autohelp (compile)
Compiled src/autohelp.erl
Compiled src/autohelp_lib.erl
Compiled src/autohelp_demo.erl
==> bson (compile)
Compiled src/bson_tests.erl
Compiled src/bson.erl
Compiled src/bson_binary.erl
==> mongodb (compile)
Compiled src/resource_pool.erl
Compiled src/mvar.erl
Compiled src/mongodb_app.erl
Compiled src/mongo_query.erl
Compiled src/mongo_replset.erl
Compiled src/mongodb_tests.erl
Compiled src/mongo_protocol.erl
Compiled src/mongo_cursor.erl
Compiled src/mongo_connect.erl
Compiled src/mongo.erl
==> parse_fight (compile)
Compiled src/parse_fight_sup.erl
Compiled src/parse_fight_app.erl
src/db_wrapper.erl: at line 19: syntax error before: ';'
src/db_wrapper.erl:none: error in parse transform 'autohelp': error
ERROR: compile failed while processing /Users/blt/projects/com/rackspace/parse_fight: rebar_abort

If {parse_transform, autohelp} is removed from rebar.config the build succeeds.

Add support for types

Typespecs are cool. It would be good to show types defined by module and types of function arguments.
Need to decide how types should be shown.

  • Module's types maybe will fit after module description printed by help/0

  • Function arg types shouldn't be in in function header because entries like

    function(Arg1::(type1|type2|long_type_name3|undefined), Arg2::integer(), ...)

    are unreadable

  • Maybe argument types should be listed after header like in man pages

  • Maybe types should be shown only in special help(...) calls (increase arity, etc.) or even in other function like help_types(...)? Not sure.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.