Docing in-and-out: Markdown introduction

DOC-ING IN AND OUTallansun.130830@KKBOX

We sometimes write some comments…

Not easy to read…

Introducing: Markdown

What is Markdown?• A lightweight markup language

• “To write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML(or HTML)”

• In brief:• Write in plaintext• Read in rich format or plaintext

Trend of Markdown

Useful to coders

Pretty Results

Maybe profitable..?

How to write?• Headings• Paragraphs• Lists• Code• Links & Images• Miscs

Headings

Paragraphs

Lists

Code

Links & Images

Miscs

So we’re now using Markdown…

• In our opensource project: KKBOX Android Toolkit• https://github.com/

KKBOX/android_kktoolkit

• README.md• .md is a markdown

extension (Optional)

• Wiki page

What about in-code comments?• We currently uses Doxygen-style comments

Comment styles

Use Doxygen to autogen docs

Step-by-step• Generate a doxygen configure file• $doxygen doxygen• See the pretty HTML

• We currently made this process cronly due to laziness• Self generate, self update

Conclusion• Writing document by using Markdown language

• Examples, explanation, blog posts, readme…• Easy to write, easy to read

• Write in-code comments by using Doxygen notations• Not much different between regular comments• Eclipse can help you a bit• Auto-generated documents

• 順手捐發票，救救老殘窮順手寫文件，救救全世界• Please give a helping hand on our open-source project :P

Refenece• Markdown Project

http://daringfireball.net/projects/markdown/

• 中文版說明http://markdown.tw/

• Github Flavored Markdownhttps://help.github.com/articles/github-flavored-markdown

• Doxygenhttp://www.doxygen.org/

Q&AThanks!