1. DOC-ING IN AND OUT
allansun.130830@KKBOX

2. We sometimes write some comments…

3. Not easy to read…

4. Introducing: Markdown

5. 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

6. Trend of Markdown

7. Useful to coders

8. Pretty Results

9. Maybe profitable..?

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

11. Headings

12. Paragraphs

13. Lists

14. Code

15. Links & Images

16. Miscs

17. So we’re now using Markdown…
• In our opensource
project: KKBOX
Android Toolkit
• https://github.com/KKBO
X/android_kktoolkit
• README.md
• .md is a markdown
extension (Optional)
• Wiki page

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

19. Comment styles

20. Use Doxygen to autogen docs

21. 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

22. 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

23. Refenece
• Markdown Project
http://daringfireball.net/projects/markdown/
• 中文版說明
http://markdown.tw/
• Github Flavored Markdown
https://help.github.com/articles/github-flavored-markdown
• Doxygen
http://www.doxygen.org/

24. Q&A
Thanks!