Permalink
Browse files

[enhance] markdown: Documentation

  • Loading branch information...
1 parent 7937522 commit 679c41af2311878e4d6291f49c4869ce195d15a6 Nicolas Glondu committed Aug 17, 2011
Showing with 63 additions and 2 deletions.
  1. +63 −2 stdlib/tools/markdown/markdown.opa
@@ -28,13 +28,34 @@
package stdlib.tools.markdown
-/*
+/**
* {1 About this module}
*
* Simple Markdwon implementation
* See http://daringfireball.net/projects/markdown/
* to learn more about Markdown.
*
+ * What you can do:
+ * - Create titles (both styles)
+ * - Insert links (both styles)
+ * - Insert images (both styles)
+ * - Make an simple or a strong emphasis (both ways: _ or *)
+ * - Make simple emphasis inside a strong one
+ * - Make strong emphasis inside a simple one
+ * - Write lists (ul or ol) with elements on one or more lines
+ * - Insert code (both ways: block or inside ``)
+ * - Insert quotes containing anything supported (including other quotes)
+ * - Insert linebreaks
+ * - Insert linefeeds
+ *
+ * What you cannot do:
+ * - Put any effect inside a title
+ * - Put any effect inside a link
+ * - Put any effect inside a emphasis
+ * - Put lists inside of lists
+ * - Put a title inside a lists
+ * - Put a block of code inside a list
+ *
*/
type Markdown.private.image =
@@ -476,7 +497,7 @@ __a _simple emphasis_ inside a strong one__.
## Lists
You can insert simple bullet lists simply by putting each element in
-a line starting by a `+`, a `+` or a `*`. Mixing symbols will not create
+a line starting by a `-`, a `+` or a `*`. Mixing symbols will not create
different lists unless there is a blanck line in the middle:
- one
@@ -626,10 +647,19 @@ with a linebreak
* End user functions
*/
+ /**
+ * Default options for Markdown parser
+ */
default_options = {
detect_text_links = false
} : Markdown.options
+ /**
+ * Transforms a string into a Markdown element
+ *
+ * @param opt Markdown configuration
+ * @param src Source string
+ */
@publish @server of_string(_opt:Markdown.options, src:string):Markdown.t =
src = "{src} "
parts = String.replace("\r", "", src)
@@ -665,12 +695,26 @@ with a linebreak
~{blocks refs}
endprocess(parts)
+ /**
+ * Transforms a Markdown element into xhtml
+ *
+ * @param opt Markdown configuration
+ * @param src Markdown source element
+ */
@publish @server to_xhtml(opt:Markdown.options, src:Markdown.t) =
List.fold(
elt, acc ->
acc <+> break <+> aux_block(opt, src.refs)(elt),
src.blocks, <></>)
+ /**
+ * Directly transforms a Markdown source text into xhtml
+ * It is in fact nothing more than a [of_string] followed by a
+ * [to_xhtml].
+ *
+ * @param opt Markdown configuration
+ * @param src Source string
+ */
@publish @server xhtml_of_string(opt:Markdown.options, src:string):xhtml =
of_string(opt, src) |> to_xhtml(opt, _)
@@ -681,6 +725,15 @@ with a linebreak
// - Close dialog: 42 request
// Manually: 0 request to open or close the dialog \o/
+ /**
+ * Main element of the Markdown help display
+ * Note that this does not show anything (you can add a CSS entry
+ * to hide markdown_help to be sure of this). Once placed in a page,
+ * use a [help_button] to add a button that will allow the user to
+ * see this help.
+ *
+ * @param id Identifier of the help element
+ */
help_div(id) =
src_id = "{id}_source"
res_id = "{id}_result"
@@ -727,6 +780,14 @@ with a linebreak
do Dom.set_style(#{content_sel}, style)
void
+ /**
+ * Displays a button to show Markdown help
+ * Note that there MUST be a [help_div] somewhere in the page for this
+ * to actually show something.
+ *
+ * @param id Identifier of the help element
+ * @param content Content of the link
+ */
help_button(id, content:xhtml) =
<a class="markdown_help_button" onclick={_->do_expand(id)}>{content}</a>

0 comments on commit 679c41a

Please sign in to comment.