Redux-like message bus documentation

[jdylanstewart]

DISCLAMER: I have only been working with auto documentation for a few months now, so I might be missing something simple.

I realize this is WAY outside of the scope of things you are likely thinking about right now, but I thought I would leave it here as food for thought.

Documenting message bus architecture has been a challenge for me for a while now and after asking around a lot, have not really gotten a good solution for.

In Redux (or similar message bus architectures a la Socket.io, webworkers etc) there is a very cleanly defined actionTypes/actions/reducers format which presents documentation challenges.

Example:

actions.js

 export const ADD_TODO = 'ADD_TODO';
 
 export function addTodo(todo) {
   return ({
     type: ADD_TODO,
     todo: todo,
   });
 }

reducers.js

export default function todoReducers(state = initialState, action) {
  switch (action.type) {
    case ADD_TODO: {
      return state.push(action.todo);
    }
    default: {
      return state;
    }
  }
}

todoApp.js

import { createStore } from 'redux'
import addTodo from './actions';
import todoReducers from './reducers';

const store = createStore(todoReducers);

const todoItem = { msg: 'do yo thang' };

store.dispatch(addTodo(todoItem));

Now, in the mental model of the design, there is a very clear coupling of the actionType constant string, the action creator functions, and the associated reducer case in such a way as it would be beneficial to document them together (at least in a linked documentation way). However, it also makes sense to keep them in separate files for clarity reasons (I'll direct details of that to http://redux.js.org/docs/recipes/ReducingBoilerplate.html).

Again, I recognize this is likely outside the scope of what you are working on, but I think it represents a problem with auto documentation and associating spatially disparate pieces of documentation together that is at least worth a discussion.

[typhonrt]

This is definitely an area I'd like to address in the coming months. The right solution though is a challenge as existing JSDoc tags: @event, @fires, @listens don't exactly fit this pattern.

TJSDoc itself is built via an in-process eventbus though it's structured even then the above JSDoc tags don't seemingly capture all of the potential interactions. The React examples are definitely of a more adhoc / unstructured format making things a bit trickier per se.

I'm certainly going to be working toward doc generation and interactive graphs for the in-process eventbus pattern. This may provide one path toward documenting less structured mechanisms of passing around / filtering object data.

It will definitely be a work in progress and hopefully the expanded functionality of TJSDoc for 3rd party plugins could come into play for initial prototyping if not handling the majority of the heavy lifting for the scenario you describe.