using ExDoc to generate documentation for a single module?

[Simon St.Laurent]

I really like the look of the documentation ExDoc creates, but I'm having trouble getting it to actually generate documentation for simple projects.

I'm trying to generate documentation for the Drop module, drop.ex. The files are not in a github repository - that would be overkill at the moment.  If I use:

elixir -pa ebin /Users/simonstl/Documents/personal/elixir/exdoc/bin/exdoc "Drop" "0.1" -m "Drop"

It generates empty documentation, only noting the information provided in the command line.

Can ExDoc be used this way?  Or do I need to create a more complete application before I can use it?

(The documentation in the drop.ex module comes up just fine from the h command in IEx.)

Thanks,
Simon

[José Valim]

I really like the look of the documentation ExDoc creates, but I'm having trouble getting it to actually generate documentation for simple projects.

I'm trying to generate documentation for the Drop module, drop.ex. The files are not in a github repository - that would be overkill at the moment.  If I use:

elixir -pa ebin /Users/simonstl/Documents/personal/elixir/exdoc/bin/exdoc "Drop" "0.1" -m "Drop"

This was supposed to work as long as everything is compiled.

Talking about docs, Alexei (alco/true_droid) did the excellent job of adding a Mix task to ExDoc.

This means anyone can add ExDoc to their mix files and then simply run "mix docs" to get the project compilation back. I think this is way easier to use, I will update ExDoc README today and ping this thread.

[José Valim]

I have updated ExDoc README to contain instruction to run with Mix projects. I had also to change the project location, so you can find the new URL here: https://github.com/elixir-lang/ex_doc

Simon, let me know if you run into any error using the Mix approach.

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Lead Developer

[Simon St.Laurent]

On Wednesday, April 24, 2013 1:20:10 PM UTC-4, José Valim wrote:

I have updated ExDoc README to contain instruction to run with Mix projects. I had also to change the project location, so you can find the new URL here: https://github.com/elixir-lang/ex_doc

Simon, let me know if you run into any error using the Mix approach.

 
I can do that, but now I get to explain projects and dependencies to readers while they're still learning what modules and functions are.

I guess the other option is to punt on "documentation early and often" and wait to cover it until much later in the book when readers know what mix is.

Thanks,
Simon

[Alexei Sholik]

Mix is not rocket science and is very easy to pick up with little Elixir knowledge. You just follow instructions and boom -- you get yourself some dependency management and easy testing/building/running. You could simply direct your readers to the Getting Started page[1] (perhaps as an exercise) even early on.

  [1]: http://elixir-lang.org/getting_started/mix/1.html

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

--
Best regards
Alexei Sholik

[José Valim]

I can do that, but now I get to explain projects and dependencies to readers while they're still learning what modules and functions are. 

Oh! The command line should still work though, let's try to figure out why it doesn't. Can you put the code online? I would love to give it a shot.

 

I guess the other option is to punt on "documentation early and often" and wait to cover it until much later in the book when readers know what mix is.

Maybe there are other benefits we could show early on about documentation? Maybe doctests?

Then after they wrote a good amount of documentation, you can introduce them to ExDoc for extra awe? :)

[Simon St.Laurent]

On Wednesday, April 24, 2013 1:36:45 PM UTC-4, José Valim wrote:

I can do that, but now I get to explain projects and dependencies to readers while they're still learning what modules and functions are. 

Oh! The command line should still work though, let's try to figure out why it doesn't. Can you put the code online? I would love to give it a shot.

I'll post it tonight.  ExDoc runs, it just generates mostly emptiness.
 

 

I guess the other option is to punt on "documentation early and often" and wait to cover it until much later in the book when readers know what mix is.

Maybe there are other benefits we could show early on about documentation? Maybe doctests?

They aren't likely ready for that, but...
 

Then after they wrote a good amount of documentation, you can introduce them to ExDoc for extra awe? :)

This part, absolutely!

Thanks,
Simon

[Simon St.Laurent]

On Wednesday, April 24, 2013 1:36:31 PM UTC-4, alco wrote:

Mix is not rocket science and is very easy to pick up with little Elixir knowledge. You just follow instructions and boom -- you get yourself some dependency management and easy testing/building/running. You could simply direct your readers to the Getting Started page[1] (perhaps as an exercise) even early on.

  [1]: http://elixir-lang.org/getting_started/mix/1.html

For some of my readers, "not rocket science" will be perfectly fine.  For others, especially as Elixir moves past the initial early adopter experts, it needs to go much much more slowly.  I, er, wasn't even planning on covering testing in the initial release...

The purpose of Introducing Elixir, like Introducing Erlang, isn't just "here's a cool language and tools" - it's about bringing that cool language and tools to a much broader audience than the usual functional programming audience.

We'll see!

Thanks,
Simon

[Jeremy Huffman]

I would think mix should come before ExDoc. @doc is mostly relevant to someone writing a library; I would not even want to try and tell someone how to use a library without covering mix & deps.

--

[Simon St.Laurent]

On Wednesday, April 24, 2013 3:08:44 PM UTC-4, Jeremy Huffman wrote:

@doc is mostly relevant to someone writing a library;

Maybe.  I try to encourage programmers to include documentation from their earliest days.  Admittedly, I'm not consistent about doing it either, but getting the "there is more than comments out there" message in readers' heads early seems to help.

Also, specific to Elixir, I'm especially happy that IEx's h can pull documentation to the console easily.  That's a small but glorious thing.

(ExDoc just looks cool and provides a 'real' reason to use Markdown.)

Thanks,
Simon

[Dave Thomas]

On Wed, Apr 24, 2013 at 12:20 PM, José Valim <jose....@plataformatec.com.br> wrote:

I have updated ExDoc README to contain instruction to run with Mix projects. I had also to change the project location, so you can find the new URL here: https://github.com/elixir-lang/ex_doc

This is brilliant, and so much easier to explain. Thank you for this.

Dave

 

[Simon St.Laurent]

On Wednesday, April 24, 2013 1:36:45 PM UTC-4, José Valim wrote:

I can do that, but now I get to explain projects and dependencies to readers while they're still learning what modules and functions are. 

Oh! The command line should still work though, let's try to figure out why it doesn't. Can you put the code online? I would love to give it a shot.

 The module code is embarrassingly simple - it's chapter 2 after all.

------------------------------------------------------------------------------------------
defmodule Drop do
  @moduledoc """
  Functions calculating velocities achieved by objects dropped in a vacuum.
 
  from *Introducing Elixir*, O'Reilly Media, Inc., 2013. 
  Copyright 2013 by Simon St.Laurent and J. David Eisenberg.
  """
  @vsn 0.1

@doc """
Calculates the velocity of an object falling on Earth
as if it were in a vacuum (no air resistance).  The distance is
the height from which the object falls, specified in meters,
and the function returns a velocity in meters per second.
"""

@spec fall_velocity(number) :: number

  def fall_velocity(distance) do
    import :default, :math, only: [sqrt: 1] 

    sqrt(2 * 9.8 * distance)
  end
end
------------------------------------------------------------------------------------------

h works fine from IEx.  s and t do not:

------------------------------------------------------------------------------------------
iex(15)> c("drop.ex")       
/Users/simonstl/Documents/personal/IntroElixir/code/ch02/ex5-docs/drop.ex:1: redefining module Drop
[Drop]
iex(16)> h Drop              
# Drop

Functions calculating velocities achieved by objects dropped in a vacuum.

from *Introducing Elixir*, O'Reilly Media, Inc., 2013.  Copyright 2013 by Simon St.Laurent and J. David Eisenberg.
:ok
iex(17)> h Drop.fall_velocity
* def fall_velocity(distance)

Calculates the velocity of an object falling on Earth
as if it were in a vacuum (no air resistance).  The distance is
the height from which the object falls, specified in meters,
and the function returns a velocity in meters per second.

:ok
iex(18)> s Drop.fall_velocity
No specs for Drop.fall_velocity have been found
:ok
iex(19)> t Drop.fall_velocity
No types for Drop.fall_velocity have been found
:ok
------------------------------------------------------------------------------------------

Getting to ExDoc:

elixir -pa ebin /Users/ssl/Documents/personal/elixir/exdoc/bin/exdoc "Drop" "0.1" -m "Drop"

Gives me a nice new docs directory.  The top left corner of index.html shows

Drop v0.1
Modules | Records | Protocols
Search: _________


But there is nothing else there, even if I click on the links.  Given that s and t don't work, I thought it might be the @spec, but taking it out and rerunning ExDoc produces the same empty result.

All suggestions welcome.  As always, I won't be surprised if I've just botched something, but I don't see it.

Thanks,
Simon

[Yurii Rashkovskii]

s and t helpers don't work for modules compiled to memory because underlying beam_lib can only access the contents of the beam file if it's on the disk. It would be really great to sole this problem, though. Either on Erlang's side or elixir's.

--

[Simon St.Laurent]

On Wednesday, April 24, 2013 9:02:08 PM UTC-4, Yurii Rashkovskii wrote:

s and t helpers don't work for modules compiled to memory because underlying beam_lib can only access the contents of the beam file if it's on the disk. It would be really great to sole this problem, though. Either on Erlang's side or elixir's.

That sounds like a headache, but this does generate an actual BEAM file, attached.

Also, apologies for my weird import of the :math.sqrt function in the example.  That was lingering from a prior demo, but simplifying it doesn't affect the rest of the results.

Thanks,
Simon
 

[Yurii Rashkovskii]

I'm not in front of my computer at the moment, but just in case would you mind trying to delete the existing file, compile it with c and check whether the file exists?

--

[Yurii Rashkovskii]

Also, did you have a prior user of this module in the same iex session? If yes, have you tried using the l helper?

[Simon St.Laurent]

On Wednesday, April 24, 2013 9:11:59 PM UTC-4, Yurii Rashkovskii wrote:

Also, did you have a prior user of this module in the same iex session? If yes, have you tried using the l helper?

Here's a completely clean session, having deleted Elixir-Drop.beam, which reappears on compilation.

Interactive Elixir (0.8.2) - press Ctrl+C to exit (type h() ENTER for help)
iex(1)> c("drop.ex")
[Drop]
iex(2)> Drop.fall_velocity(20)
19.79898987322333
iex(3)> h Drop.fall_velocity

* def fall_velocity(distance)

Calculates the velocity of an object falling on Earth
as if it were in a vacuum (no air resistance).  The distance is
the height from which the object falls, specified in meters,
and the function returns a velocity in meters per second.

:ok

iex(4)> s Drop.fall_velocity

No specs for Drop.fall_velocity have been found
:ok

iex(5)> t Drop.fall_velocity

No types for Drop.fall_velocity have been found
:ok
 

I hope that helps!

Thanks,
Simon

[Yurii Rashkovskii]

I'll take a look tonight or tomorrow morning. Need to get back to the computer for this! :)

--

[José Valim]

Maybe we are not compiling with specs? If that is the case, we should have a more appropriated error message.

--

[José Valim]

Back from travelling. Is this still an issue?

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Lead Developer

[J David Eisenberg]

On Friday, May 3, 2013 10:55:31 AM UTC-7, José Valim wrote:

Back from travelling. Is this still an issue?

It's still somewhat problematic. Given this code:

#==============
defmodule Drop do

  @spec fall_velocity(number) :: number

  def fall_velocity(distance) do

    :math.sqrt(2 * 9.8 * distance)
  end
end
#=============

I compiled it using elixirc, then went into the shell, and then s() worked fine. However, if you compile within IEx, then it no longer works.

iex(1)> s(Drop.fall_velocity)
@spec fall_velocity(number()) :: number()
:ok
iex(2)> c("drop.ex")
/home/david/introducing_elixir/code/ch02/ex5-docs/drop.ex:1: redefining module Drop
[Drop]
iex(3)> s(Drop.fall_velocity)

To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-core+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.
 
 

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.

To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-core+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.
 
 

[José Valim]

I believe it is fixed in master. :)

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Lead Developer

To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.