Docing in-and-out: Markdown introduction

1,096 views

Published on

Published in: Technology
0 Comments
2 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
1,096
On SlideShare
0
From Embeds
0
Number of Embeds
6
Actions
Shares
0
Downloads
8
Comments
0
Likes
2
Embeds 0
No embeds

No notes for slide

Docing in-and-out: Markdown introduction

  1. 1. DOC-ING IN AND OUT allansun.130830@KKBOX
  2. 2. We sometimes write some comments…
  3. 3. Not easy to read…
  4. 4. Introducing: Markdown
  5. 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. 6. Trend of Markdown
  7. 7. Useful to coders
  8. 8. Pretty Results
  9. 9. Maybe profitable..?
  10. 10. How to write? • Headings • Paragraphs • Lists • Code • Links & Images • Miscs
  11. 11. Headings
  12. 12. Paragraphs
  13. 13. Lists
  14. 14. Code
  15. 15. Links & Images
  16. 16. Miscs
  17. 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. 18. What about in-code comments? • We currently uses Doxygen-style comments
  19. 19. Comment styles
  20. 20. Use Doxygen to autogen docs
  21. 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. 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. 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. 24. Q&A Thanks!

×