Please THOROUGHLY document all automagic involved in the "sources" functionality

[rulatir]

Point by point analysis of the shortcomings of the documentation at http://alt.js.org/docs/async/

The example content of sources/SearchSource.js begins thus:

const SearchSource = {
  performSearch: {

Regarding the performSearch key, it is not explained to what extent the the name of this key is arbitrary, and to what extent it is dictated by a naming convention expected by the automagic. Is the 'perform' part arbitrary, or a naming convention? Is the 'Search' part arbitrary or required to match the use of the word 'Search' as (part of) the name of something else somewhere else?

Next, regarding the names of actions that are "bound" to "methods" in the source object:

    loading: SearchActions.loadingResults, // (optional)
    success: SearchActions.receivedResults, // (required)
    error: SearchActions.fetchingResultsFailed, // (required)

How arbitrary are those?

Then, what exactly does registerAsync() do? I would expect an explanation in the following form:

For each key in the source object, if the key has the form ((some kind of naming convention specification if applicable)), then the following members are added to the store instance:

• ((specification of how the member name is constructed from name parts parsed from the source object key name, if applicable, otherwise just plain member name)) - ((type of the member and documentation of what it does, at what point in the whole async control flow it is used or called and by what))
• ((specification of how the member name is constructed from name parts parsed from the source object key name, if applicable, otherwise just plain member name)) - ((type of the member and documentation of what it does, at what point in the whole async control flow it is used or called and by what))
• ...

I would also like to find a thorough explanation of:

• if applicable, how methods added to the store object map to the underlying functionality of actions and stores (sans sources)
• if applicable, what parts of the underlying functionality of actions and stores (sans sources) are bypassed by the sources mechanism and replaced by different logic
• if applicable, what parts of the functionality injected by the sources mechanism are not handled automagically and require additional boilerplate according to the usual art of using actions and stores (sans sources); specifically, which methods added to the store by registerAsync() must still be separately 'bound' to actions in order to ever be called