Document where the main algorithm is implemented and how it works

[ian-kelling]

I've been recently been working on a similar project for emacs, https://github.com/ian-kelling/spray.

Based on a quick count, similar programs are implemented in 6 languages, 9 platforms and 11+ projects. Every one has a similar algorithm to choose a word, an accent character and an interval to display it. How to do that best is quite important. However, how each project does it is generally buried in unrelated code, and mostly undocumented. It is prohibitively time consuming to figure out the algorithm and differences between them for each project. This sucks. Users would like to know so they can pick one. Developers would like to know so they can get ideas and spread improvements among different projects.

A few minutes of work from each project's maintainer can fix this. Please document which file(s), function(s), etc. implement the main algorithm, and preferably how it works in plain english or pseudocode. An example for the my own project is at: https://github.com/ian-kelling/spray#algorithm-details.