docstring for imported symbols

dmlc · Oct 21, 2015 · 2c945ea · 2c945ea
1 parent 9223721
commit 2c945ea
Show file tree

Hide file tree

Showing 5 changed files with 57 additions and 31 deletions.
diff --git a/docs/api/ndarray.md b/docs/api/ndarray.md
@@ -32,7 +32,7 @@ object (`NDArray`) is returned. Otherwise, a tuple containing all the outputs wi
 
 
 *source:*
-[MXNet/src/ndarray.jl:380](https://github.com/dmlc/MXNet.jl/tree/d13ddc6542bdb00e26b87e721a9b0e79a22bbd66/src/ndarray.jl#L380)
+[MXNet/src/ndarray.jl:380](https://github.com/dmlc/MXNet.jl/tree/92237212c594440455567ec4d39caec909ddd11e/src/ndarray.jl#L380)
 
 ---
 
@@ -41,7 +41,7 @@ object (`NDArray`) is returned. Otherwise, a tuple containing all the outputs wi
 Copy data from NDArray to Julia Array
 
 *source:*
-[MXNet/src/ndarray.jl:187](https://github.com/dmlc/MXNet.jl/tree/d13ddc6542bdb00e26b87e721a9b0e79a22bbd66/src/ndarray.jl#L187)
+[MXNet/src/ndarray.jl:187](https://github.com/dmlc/MXNet.jl/tree/92237212c594440455567ec4d39caec909ddd11e/src/ndarray.jl#L187)
 
 ---
 
@@ -50,7 +50,7 @@ Copy data from NDArray to Julia Array
 Copy data between NDArrays
 
 *source:*
-[MXNet/src/ndarray.jl:175](https://github.com/dmlc/MXNet.jl/tree/d13ddc6542bdb00e26b87e721a9b0e79a22bbd66/src/ndarray.jl#L175)
+[MXNet/src/ndarray.jl:175](https://github.com/dmlc/MXNet.jl/tree/92237212c594440455567ec4d39caec909ddd11e/src/ndarray.jl#L175)
 
 ---
 
@@ -59,7 +59,7 @@ Copy data between NDArrays
 Copy data from Julia Array to NDArray
 
 *source:*
-[MXNet/src/ndarray.jl:195](https://github.com/dmlc/MXNet.jl/tree/d13ddc6542bdb00e26b87e721a9b0e79a22bbd66/src/ndarray.jl#L195)
+[MXNet/src/ndarray.jl:195](https://github.com/dmlc/MXNet.jl/tree/92237212c594440455567ec4d39caec909ddd11e/src/ndarray.jl#L195)
 
 ---
 
@@ -68,7 +68,7 @@ Copy data from Julia Array to NDArray
 Create copy: NDArray -> Julia Array
 
 *source:*
-[MXNet/src/ndarray.jl:205](https://github.com/dmlc/MXNet.jl/tree/d13ddc6542bdb00e26b87e721a9b0e79a22bbd66/src/ndarray.jl#L205)
+[MXNet/src/ndarray.jl:205](https://github.com/dmlc/MXNet.jl/tree/92237212c594440455567ec4d39caec909ddd11e/src/ndarray.jl#L205)
 
 ---
 
@@ -77,7 +77,7 @@ Create copy: NDArray -> Julia Array
 Create copy: NDArray -> NDArray in a given context
 
 *source:*
-[MXNet/src/ndarray.jl:211](https://github.com/dmlc/MXNet.jl/tree/d13ddc6542bdb00e26b87e721a9b0e79a22bbd66/src/ndarray.jl#L211)
+[MXNet/src/ndarray.jl:211](https://github.com/dmlc/MXNet.jl/tree/92237212c594440455567ec4d39caec909ddd11e/src/ndarray.jl#L211)
 
 ---
 
@@ -86,7 +86,7 @@ Create copy: NDArray -> NDArray in a given context
 Create copy: Julia Array -> NDArray in a given context
 
 *source:*
-[MXNet/src/ndarray.jl:217](https://github.com/dmlc/MXNet.jl/tree/d13ddc6542bdb00e26b87e721a9b0e79a22bbd66/src/ndarray.jl#L217)
+[MXNet/src/ndarray.jl:217](https://github.com/dmlc/MXNet.jl/tree/92237212c594440455567ec4d39caec909ddd11e/src/ndarray.jl#L217)
 
 ---
 
@@ -95,7 +95,7 @@ Create copy: Julia Array -> NDArray in a given context
 Create NDArray and initialize with 1
 
 *source:*
-[MXNet/src/ndarray.jl:118](https://github.com/dmlc/MXNet.jl/tree/d13ddc6542bdb00e26b87e721a9b0e79a22bbd66/src/ndarray.jl#L118)
+[MXNet/src/ndarray.jl:118](https://github.com/dmlc/MXNet.jl/tree/92237212c594440455567ec4d39caec909ddd11e/src/ndarray.jl#L118)
 
 ---
 
@@ -104,7 +104,7 @@ Create NDArray and initialize with 1
 Assign all elements of an NDArray to a scalar
 
 *source:*
-[MXNet/src/ndarray.jl:155](https://github.com/dmlc/MXNet.jl/tree/d13ddc6542bdb00e26b87e721a9b0e79a22bbd66/src/ndarray.jl#L155)
+[MXNet/src/ndarray.jl:155](https://github.com/dmlc/MXNet.jl/tree/92237212c594440455567ec4d39caec909ddd11e/src/ndarray.jl#L155)
 
 ---
 
@@ -116,7 +116,7 @@ Get the shape of an `NDArray`. Note the shape is converted to Julia convention.
 
 
 *source:*
-[MXNet/src/ndarray.jl:84](https://github.com/dmlc/MXNet.jl/tree/d13ddc6542bdb00e26b87e721a9b0e79a22bbd66/src/ndarray.jl#L84)
+[MXNet/src/ndarray.jl:84](https://github.com/dmlc/MXNet.jl/tree/92237212c594440455567ec4d39caec909ddd11e/src/ndarray.jl#L84)
 
 ---
 
@@ -130,7 +130,7 @@ used in data parallelization to split mini-batch into sub-batches for different
 
 
 *source:*
-[MXNet/src/ndarray.jl:137](https://github.com/dmlc/MXNet.jl/tree/d13ddc6542bdb00e26b87e721a9b0e79a22bbd66/src/ndarray.jl#L137)
+[MXNet/src/ndarray.jl:137](https://github.com/dmlc/MXNet.jl/tree/92237212c594440455567ec4d39caec909ddd11e/src/ndarray.jl#L137)
 
 ---
 
@@ -139,7 +139,7 @@ used in data parallelization to split mini-batch into sub-batches for different
 Create zero-ed NDArray of specific shape
 
 *source:*
-[MXNet/src/ndarray.jl:105](https://github.com/dmlc/MXNet.jl/tree/d13ddc6542bdb00e26b87e721a9b0e79a22bbd66/src/ndarray.jl#L105)
+[MXNet/src/ndarray.jl:105](https://github.com/dmlc/MXNet.jl/tree/92237212c594440455567ec4d39caec909ddd11e/src/ndarray.jl#L105)
 
 ---
 
@@ -157,7 +157,7 @@ have shape (28,28,1,100).
 
 
 *source:*
-[MXNet/src/ndarray.jl:32](https://github.com/dmlc/MXNet.jl/tree/d13ddc6542bdb00e26b87e721a9b0e79a22bbd66/src/ndarray.jl#L32)
+[MXNet/src/ndarray.jl:32](https://github.com/dmlc/MXNet.jl/tree/92237212c594440455567ec4d39caec909ddd11e/src/ndarray.jl#L32)
 
 ---
 
@@ -185,5 +185,5 @@ which will do inplace adding of the contents of b into a.
 
 
 *source:*
-[MXNet/src/ndarray.jl:247](https://github.com/dmlc/MXNet.jl/tree/d13ddc6542bdb00e26b87e721a9b0e79a22bbd66/src/ndarray.jl#L247)
+[MXNet/src/ndarray.jl:247](https://github.com/dmlc/MXNet.jl/tree/92237212c594440455567ec4d39caec909ddd11e/src/ndarray.jl#L247)
 
diff --git a/docs/api/symbol.md b/docs/api/symbol.md
@@ -9,7 +9,7 @@
 Get a new grouped symbol whose output contains all the internal outputs of this symbol.
 
 *source:*
-[MXNet/src/symbol.jl:63](https://github.com/dmlc/MXNet.jl/tree/d13ddc6542bdb00e26b87e721a9b0e79a22bbd66/src/symbol.jl#L63)
+[MXNet/src/symbol.jl:63](https://github.com/dmlc/MXNet.jl/tree/92237212c594440455567ec4d39caec909ddd11e/src/symbol.jl#L63)
 
 ---
 
@@ -18,7 +18,7 @@ Get a new grouped symbol whose output contains all the internal outputs of this
 Create a symbol that groups symbols together
 
 *source:*
-[MXNet/src/symbol.jl:77](https://github.com/dmlc/MXNet.jl/tree/d13ddc6542bdb00e26b87e721a9b0e79a22bbd66/src/symbol.jl#L77)
+[MXNet/src/symbol.jl:77](https://github.com/dmlc/MXNet.jl/tree/92237212c594440455567ec4d39caec909ddd11e/src/symbol.jl#L77)
 
 ---
 
@@ -33,7 +33,7 @@ Most operators do not have Auxiliary states.
 
 
 *source:*
-[MXNet/src/symbol.jl:58](https://github.com/dmlc/MXNet.jl/tree/d13ddc6542bdb00e26b87e721a9b0e79a22bbd66/src/symbol.jl#L58)
+[MXNet/src/symbol.jl:58](https://github.com/dmlc/MXNet.jl/tree/92237212c594440455567ec4d39caec909ddd11e/src/symbol.jl#L58)
 
 ---
 
@@ -42,5 +42,5 @@ Most operators do not have Auxiliary states.
 Create a symbolic variable with the given name
 
 *source:*
-[MXNet/src/symbol.jl:70](https://github.com/dmlc/MXNet.jl/tree/d13ddc6542bdb00e26b87e721a9b0e79a22bbd66/src/symbol.jl#L70)
+[MXNet/src/symbol.jl:70](https://github.com/dmlc/MXNet.jl/tree/92237212c594440455567ec4d39caec909ddd11e/src/symbol.jl#L70)
 
diff --git a/docs/build.jl b/docs/build.jl
@@ -3,17 +3,6 @@ using Lexicon
 
 config = Config(md_permalink = false, mathjax = true)
 
-function save_meta(file :: AbstractString, docs :: Lexicon.Metadata, order = [:source])
-  isfile(file) || mkpath(dirname(file))
-  open(file, "w") do io
-    for (k,v) in Lexicon.EachEntry(docs, order = order)
-      name = Lexicon.writeobj(k)
-      println(io, "#### $name")
-      println(io, v.docs.data)
-    end
-  end
-end
-
 doc = Lexicon.metadata(MXNet.mx)
 for mod in [:ndarray, :symbol]
   save("api/$mod.md", MIME("text/md"), filter(doc, files=["$mod.jl"]), config)

diff --git a/src/symbol.jl b/src/symbol.jl
@@ -256,6 +256,14 @@ function _define_atomic_symbol_creator(hdr :: MX_handle)
   kv_nargs_s = bytestring(ref_kv_nargs[])
   kv_nargs   = symbol(kv_nargs_s)
 
+  f_desc = bytestring(ref_desc[]) * "\n\n"
+  if !isempty(kv_nargs_s)
+    f_desc *= "This function support variable length positional `Symbol` inputs.\n\n"
+  end
+  f_desc *= _format_docstring(Int(ref_nargs[]), ref_arg_names, ref_arg_types, ref_arg_descs)
+  f_desc *= "* `name`: Julia Symbol (e.g. `:my_symbol`), optional.\n\n  The name of the symbol.\n\n"
+  f_desc *= "**Returns**\n\n`symbol`: `mx.Symbol`\n\n  The constructed symbol."
+
   # function $func_name(args...; kwargs...)
   func_head = Expr(:call, func_name, Expr(:parameters, Expr(:..., :kwargs)), Expr(:..., :args))
   func_body = quote
@@ -324,8 +332,8 @@ function _define_atomic_symbol_creator(hdr :: MX_handle)
   func_def = Expr(:function, func_head, Expr(:block, func_body))
   eval(func_def)
 
-  # TODO: add doc string
-  # eval(:(@doc($doc_str, $func_name)))
+  # add doc string
+  eval(:(@doc($f_desc, $func_name)))
 end
 
 function _import_atomic_symbol_creators()

diff --git a/src/util.jl b/src/util.jl
@@ -1,3 +1,6 @@
+################################################################################
+# Dataset related utilities
+################################################################################
 function get_data_dir()
   data_dir = joinpath(Pkg.dir("MXNet"), "data")
   mkpath(data_dir)
@@ -38,3 +41,29 @@ function get_cifar10()
   filenames[:mean] = joinpath(cifar10_dir, "cifar/cifar_mean.bin")
   return filenames
 end
+
+
+################################################################################
+# Internal Utilities
+################################################################################
+function _format_docstring(narg::Int, arg_names::Ref{char_pp}, arg_types::Ref{char_pp}, arg_descs::Ref{char_pp}, remove_dup::Bool=true)
+  param_keys = Set{AbstractString}()
+
+  arg_names  = pointer_to_array(arg_names[], narg)
+  arg_types  = pointer_to_array(arg_types[], narg)
+  arg_descs  = pointer_to_array(arg_descs[], narg)
+  docstrings = AbstractString[]
+
+  for i = 1:narg
+    arg_name = bytestring(arg_names[i])
+    if arg_name ∈ param_keys && remove_dup
+      continue
+    end
+    push!(param_keys, arg_name)
+
+    arg_type = bytestring(arg_types[i])
+    arg_desc = bytestring(arg_descs[i])
+    push!(docstrings, "* `$arg_name`: $arg_type\n\n  $arg_desc\n\n")
+  end
+  return "**Parameters**\n\n$(join(docstrings, "\n"))"
+end