On 6 Jan 2016, at 13:41, David Matthews <David.Matthews at prolingua.co.uk> wrote:
On 05/01/2016 05:51, Lucas Dixon wrote:
I recommend using github markdown in the repository for documentation. Make a top level readme.md file and/or docs directory with documentation. This makes it easy for others to submit pull requests to update improve documentation too.
The documentation is already in the "documentation" directory but it's HTML rather than markdown. Would there be any advantage in changing it to markdown?
The only benefit for Markdown is that GitHub will render it when you view the file online (and the README is shown below the root tree).
Most of the documentation relates to the signatures of library functions. It would be really nice to be able to have the descriptions of the functions contained in comments in the library source itself and then have a program that would automatically turn the ML signature and the special comments into HTML. I think there are such things for other languages although I've never used them. Is there such a thing for ML? This would make it much easier to keep the source code and the documentation in sync.
A quick search reveals https://github.com/standardml/SMLDoc, though I have no idea how well it works.
James