Documenting Code

In literate wiki we take an approach to documenting code which essentially boils down to two things: 1. Granular documentation 1. Documentation is code

This usually boils dow to providing an enhanced wiki-like writing experience, in which the code is embedded or hyperlinked to the documentation in a semantically meaningful way. This core test is can code reliably interpret these wiki-pages so as to compile or otherwise run the code?

An author should have the choice - either to write in the text-editors or IDE of their choice, or to write the code in wiki. Currently in the LCW development environment we tend to write from within Livecode, using the built in IDE to edit code, and an embedded browser and other integrations to write wiki. We look to weave these two user experience together to produce as simple an integrated development environment as possible.

# Example We are currently researching examples of code writing and documentation that fit with the paradigm described here. Most examples seem to follow the Javadoc or jsdoc paradigm. This is too ugly a reading and writing experience to be useful in the social context we envisage.

The best example we find so far is with Inform 7, but this lacks the media aspects we require and the augmented writing practice we aspire to in wiki.

# Function as a service We wonder whether the FAAS programming paradigm provides us with some examples. Surely if we are able to run individual functions as a service and accompany them with tests - then we should find a range of tools to make the documentation of these individual functions easy?

Reading this blog post on OpenFAAS and Istio looks interesting and possibly quite simple to get up and running: - https://jsdoc.app/about-getting-started.html - https://www.openfaas.com/blog/istio-functions/

The following examples blog post shows how you might wish to document an R function on OpenFAAS, the question is can we make this functionality not simply described but to `runs in literate wiki: - R-templates on openFAAS.com