transduce / transformer Description

[Undistraction]

The docs for transduce say:

A transformer is an an object that provides a 2-arity reducing iterator function, step, 0-arity initial value function, init, and 1-arity result extraction function, result. The step function is used as the iterator function in reduce. The result function is used to convert the final accumulator into the return type and in most cases is R.identity. The init function can be used to provide an initial accumulator, but is ignored by transduce.

Although Ramda's docs are really excellent, this is hugely confusing for the following reasons:

• It doesn't explain that there are multiple functions in the lib that can be used as transducers (map, filter etc).
• It doesn't explain how these functions can be used as transducers. It shows map being used within a function called transducer which is counter intuitive if map is a transducer.
• It doesn't clearly explain what a transformer's signature should be and doesn't give an example of a custom transformer. A simple example of a vanilla transformer function would be really helpful here.

Transducers are tricky to understand anyway, and even though I know your docs are minimal, I thought this one was worth looking at.

[CrossEye]

See #950 and #1269 for more information.

If you have suggestions for how to update the documentation to capture this better, we'd love to hear them.

[Undistraction]

Just to be clear, I'm not suggesting you need to explain transducers - there are lots of resources for understanding them online. However I think there is a lack of information about Ramda's implementation of transducers. I guess ideally there would be a layer on top of the docs for discussing the bigger picture (or bigger pictures).

If you have suggestions for how to update the documentation to capture this better

I'm struggling to suggest how to improve the docs because I don't fully understand their use in the context of Ramda. All I can do is outline the questions I'm left with which I will do, though I fully appreciate this isn't a help forum, so that's probably not going to be very helpful.

Rereading the description I quoted above, I find it very opaque. If the examples clearly illustrated the description, then that would make it easier to decode, but they don't. So I suppose the single most useful change would be to add some more examples illustrating the description, showing a custom function that can be used as a transformer perhaps to better illustrate its signature.

[CrossEye]

I think this documentation was written by people deeply involved with adding transducers to Ramda, people who already had their head wrapped around transducers. There is a lot of room for improvement here. While I'm still looking for suggestions, I'll see if I can find a little time to try my hand at this.

[mpx2m]

I alose have the problem to understand the transduce in ramda

[bunglegrind]

in the transduce description a trasformer is defined as an object comprising three methods (init, step, result), but I couldn't find any example throughout the documentation. In the useWith description a "transformer function" is referenced, which is obviously not a transformer, but no definition is provided.

I would suggest:

1. provide examples with actual transformers
2. Move common definitions in a different page (a glossary or whatever)

[bunglegrind]

Ok, the problem with the transformer definition is that its properties are not exactly init, step, result, but they have a "@@transducer/" prefix (thanks to #1658 (comment) ).

const numbers = [1, 2, 3, 4];
const transducer = R.map(R.add(1));

R.transformer = function (init, result, step) {
  return { 
     '@@transducer/init': init, 
     '@@transducer/step': step, 
     '@@transducer/result': result                                                     
  };
};

const transformer = R.transformer(R.always(1), R.identity, R.add);
R.transduce(transducer, transformer, 0, numbers); //=> 14

const badtransformer = {init: R.always(1), step: R.add, result: R.identity};


R.transduce(transducer, badtransformer , 0, numbers); //=> t['@@transducer/step'] is not a function

it would be nice if this can be put explicitly in the documentation.
Even that R.reduce can have a transformer as first argument as well.