What is the right granularity for documenting performative texts? Our base assumption is that we need to document individual functions, but that a function might be broken up into a number of pieces.
# Example
In LCW we use the term handler to refer to several types of function - typically a function that handles an event. We store these functions in text files, and associate them with objects (or controls) int eh development environment.
All the code that we find of general use to the LCW environment we make available in a global name-space or repository that can be found at: - https;//livecode.world
In particular individual handlers are documented here: - http://handler.livecode.world
A handler can call private handlers, so we only need to document the public’s handler.
# Thoughts
It is this level of granularity that we feel is appropriate for documentation. So a single text file containing no more than one public handler. This corresponds to a micro service or function-as-aservice definition.
Often we may start with a small number of such functions or microservices bundled together in a single file. This is what we do with transporters or LCW menu controllers.
During the documentation process we often spilt these files up into individual handlers and files as part of the refactoring. This workflow seems natural and productive.