valyala / quicktemplate

Fast, powerful, yet easy to use template engine for Go. Optimized for speed, zero memory allocations in hot paths. Up to 20x faster than html/template
MIT License
3.09k stars 150 forks source link

Gentle suggestions improvements in documentation #20

Open sdwarwick opened 7 years ago

sdwarwick commented 7 years ago

this package is such a great find. thanks so much for your work. Just a few suggestions

1) notwithstanding the assumption that folks are experienced go developers, it might be a good idea to mention that function names in the template must be capitalized to be accessible.

2) the use of ./template doesn't work if you are using go build .. I have a directory that I keep both the source and executable, which is necessary for this development. build wants an absolute path names for imports. It might be worth mentioning that the location of the template folder wants to be in your source tree and referenced with an absolute path.

3) the readme.md is a great reference on the template language, but did not strike me as the "definitive reference" Perhaps it is just a change in headings, or perhaps setting up a separate document as the reference would help to quell the uneasy feeling that there is more than mentioned there.

4) the basicserver example could really use some additional comments to describe what is really going on. The use of function pointers could be discussed in more detail. It really deserves more TLC

5) finally, our intended use requires the building of templates in parallel using multiple goroutines. It would be helpful to know if the rendering part of this system can handle that. the streaming to output we handle separately.

valyala commented 7 years ago

@sdwarwick , I'll be glad accepting pull requests that enhance quicktemplate documentation.

finally, our intended use requires the building of templates in parallel using multiple goroutines. It would be helpful to know if the rendering part of this system can handle that. the streaming to output we handle separately.

Template functions are safe to call from concurrent goroutines. Unless you access shared resources inside template functions and these resources may be modified by concurrent goroutines. -race flag should help detecting such cases - see the corresponding documentation.

valyala commented 7 years ago

Here is a blog post about race detector - https://blog.golang.org/race-detector

b0o commented 6 years ago

@valyala

I have to agree about the documentation being rather lacking.

My main issue is that the syntax is not clearly and consistently defined in the README. For example, it is never explicitly stated that there exists {% if %} and {% endif %} tags - the only hint of their existence lies within some examples.

I'm in the process of building a better .qtpl syntax highlighting plugin for Vim and the lack of good documentation is what's mostly holding me back.

I may submit a PR containing my preferred improvements to the README, but some of it will be guesswork due to the fact that there doesn't exist proper documentation of some things in the first place.