docs: document folding

README.md

@@ -124,7 +124,7 @@ The goal of `nvim-treesitter` is both to provide a simple and easy way to use th
 but also to add some functionalities to it:
 Some of these features are :
   - [x] Incremental selection
-  - [ ] Syntax based code folding
+  - [x] Syntax based code folding (`set foldmethod=expr foldexpr=nvim_treesitter#foldexr()`)
   - [x] Consistent syntax highlighting (the api is not quite stable yet)
   - [x] Statusline indicator (`require'nvim-treesitter'.statusline(size)`)
 

doc/nvim-treesitter.txt

@@ -165,4 +165,16 @@ could be used as a statusline indicator.
 Note: The `size` argument is optionnal. When specified, the string will not be
       longer than `size`.
 
+|nvim_treesitter#foldexpr()|
+						  *nvim_treesitter#foldexpr()*
+
+Functions to be used to determine the fold level at a given line number.
+To use it: >
+  set foldmethod=expr
+  set foldexpr=nvim_treesitter#foldexr()
+<
+Note: This is highly experimental, and folding can break on some types of
+      edits. If you encounter such breakage, hiting `zx` should fix folding.
+      In any case, feel free to open an issue with the reproducing steps.
+
  vim:tw=78:ts=8:noet:ft=help:norl:

doc/tags

@@ -11,6 +11,7 @@ nvim-treesitter-commands	nvim-treesitter.txt	/*nvim-treesitter-commands*
 nvim-treesitter-functions	nvim-treesitter.txt	/*nvim-treesitter-functions*
 nvim-treesitter-intro	nvim-treesitter.txt	/*nvim-treesitter-intro*
 nvim-treesitter-quickstart	nvim-treesitter.txt	/*nvim-treesitter-quickstart*
+nvim_treesitter#foldexpr()	nvim-treesitter.txt	/*nvim_treesitter#foldexpr()*
 nvim_treesitter#statusline()	nvim-treesitter.txt	/*nvim_treesitter#statusline()*
 ts_api.containing_scope	nvim-treesitter.txt	/*ts_api.containing_scope*
 ts_api.get_named_children	nvim-treesitter.txt	/*ts_api.get_named_children*