goatslacker / goatslacker/alt

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

Open
#651 0 comments 2 reactions 0 assignees View on GitHub
docs
Dominant language
JavaScript
Stars
3.4k
Forks
312
PR merge metrics
No merged PRs in 30d

Description

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

Contributor guide

Open the contributing guide

Research direction

Start with the async documentation at http://alt.js.org/docs/async/ and the sources/SearchSource.js example, then inspect registerAsync(). Document which source and callback names are conventional or arbitrary, what members registerAsync() adds and how they participate in the async flow, and which action/store behavior or binding remains manual.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
32/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.