Julia: Documenting source code

Julia provide following ways to document source code.

a.   Using triple """ quotes

b.   Using @doc

Using triple """ quotes

You can document functions, methods, types in Julia by adding information in triple quotes before the definition. Documentation is interpreted as Markdown.

For example,

operations.jl

"""
 Author: Hari Krishna Gurram
 Date: 29-12-2015
 Description: Implement Arithmetic operations
"""
module Arithmetic
 export addition, subtraction, mul, div

 """
  > Calculates the sum of two numbers x, y
 """
 function addition(x, y)
  x+y
 end

 """
  > Calculates the subtraction of two numbers x, y
 """
 function subtraction(x, y)
  x-y
 end

 """
  > Calculates the multiplication of two numbers x, y
 """
 function mul(x, y)
  x*y
 end

 """
  > Calculates the division of two numbers x, y
 """
 function div(x, y)
  x/y
 end
end 

julia> include("/Users/harikrishna_gurram/study1/Julia/examples/operations.jl")
Arithmetic

julia> using Arithmetic

julia> @doc addition
  > Calculates the sum of two numbers x, y

julia> @doc subtraction
  > Calculates the subtraction of two numbers x, y

julia> @doc mul
  > Calculates the multiplication of two numbers x, y

julia> @doc div
WARNING: both Arithmetic and Base export "div"; uses of it in module Main must be qualified
ERROR: "div" is not defined in module Main
 in error at /Applications/Julia-0.4.1.app/Contents/Resources/julia/lib/julia/sys.dylib
 in which_module at /Applications/Julia-0.4.1.app/Contents/Resources/julia/lib/julia/sys.dylib
 in call at /Applications/Julia-0.4.1.app/Contents/Resources/julia/lib/julia/sys.dylib

julia> @doc Arithmetic.div
  > Calculates the division of two numbers x, y

julia> @doc Arithmetic
  Author: Hari Krishna Gurram
  Date: 29-12-2015
  Description: Implement Arithmetic operations

Observe above snippet, ‘@doc’ is used to retrieve the documentation associated with a function, module, types etc.,.

You can also use ‘?’ to retrieve the documentation associated with a function, module, types etc.,.

help?> Arithmetic
search: Arithmetic

  Author: Hari Krishna Gurram
  Date: 29-12-2015
  Description: Implement Arithmetic operations

help?> addition
search: addition

  > Calculates the sum of two numbers x, y

help?> subtraction
search: subtraction

  > Calculates the subtraction of two numbers x, y

Using @doc

@doc macro is used to set and retrieve the documentation of functions, methods, types etc., 

@doc "calculate sum" ->

  function sum(x, y) ...

  The -> is not required if the object is on the same line, e.g.

@doc "calculate sum" sum

Update operations.jl file like below.

operations.jl

@doc "
 Author: Hari Krishna Gurram
 Date: 29-12-2015
 Description: Implement Arithmetic operations
" ->
module Arithmetic
 export addition, subtraction, mul, div

 @doc " Calculates the sum of two numbers x, y" ->
 function addition(x, y)
  x+y
 end


 @doc " Calculates the subtraction of two numbers x, y " ->
 function subtraction(x, y)
  x-y
 end

 
 @doc " Calculates the multiplication of two numbers x, y" ->
 function mul(x, y)
  x*y
 end


 @doc " Calculates the division of two numbers x, y" ->
 function div(x, y)
  x/y
 end

end 

julia> include("/Users/harikrishna_gurram/study1/Julia/examples/operations.jl")
Arithmetic

julia> using Arithmetic

julia> @doc Arithmetic
  Author: Hari Krishna Gurram
  Date: 29-12-2015
  Description: Implement Arithmetic operations

julia> @doc addition
  Calculates the sum of two numbers x, y

julia> @doc mul
  Calculates the multiplication of two numbers x, y

How to retrieve documentation

By using @doc (or) ? followed by function, method, type names you can access the documentation associated with them.

help?> addition
search: addition

  Calculates the sum of two numbers x, y

help?> subtraction
search: subtraction

  Calculates the subtraction of two numbers x, y 

julia> @doc mul
  Calculates the multiplication of two numbers x, y

julia> @doc Arithmetic.div
  Calculates the division of two numbers x, y

Note:

a.   By default Julia assumes documentation available in Markdown format.

Previous                                                 Next                                                 Home