Making `withDescription` public

[wolfflow]

It'd be cool to make withDescription public for better work with plugin methods, e.g.

Bacon.pluginName = (a, b, c) ->
  f = Bacon.fromBinder (handler) ->
  #...
  Bacon.withDescription(Bacon, "pluginName", a, b, c, f)

[raimohanska]

There's the name method for giving a name for an Observable. This affects the return value of the toString and inspect methods.

Publishing withDescription would be kinda cool too, because then you could affect the description that is visible to any inspection tools (none exist at the moment).

What's your use case?

[wolfflow]

Actually, today I've been updating my Bacon.animFrame plugin having in mind an idea to make it and many other plugins "0.7.x compliant" sometime, when someone be in need to inspect their observables.

[raimohanska]

Well yeah actuallym when adding methods to Observable in a plugin, it would be nice to be able to use withDescription. I think we should publish it. The question is just, how. Maybe by adding the withDescription method to Observable.

[wolfflow]

The question is: how would we deal with "static" methods that don't extend Observable prototype directly? e.g. my Bacon.repeatedlyOnFrame plugin method is inspired by Bacon.repeatedly method and I look forward to see it like this:

Bacon.repeatedlyOnFrame = (values, divisor = 1) ->
    index = 0
    f = Bacon.scheduleAnimFrame()
      .scan(0, (x) -> x + 1)
      .filter((tick) -> !(tick % divisor))
      .map(-> values[index++ % values.length])
      .toEventStream()
   Bacon.withDescription(Bacon, "repeatedlyOnFrame", values, divisor, f)

[raimohanska]

I don't see a problem. Why not just

Bacon.repeatedlyOnFrame = (values, divisor = 1) ->
    index = 0
    f = Bacon.scheduleAnimFrame()
      .scan(0, (x) -> x + 1)
      .filter((tick) -> !(tick % divisor))
      .map(-> values[index++ % values.length])
      .toEventStream()
      .withDescription(Bacon, "repeatedlyOnFrame", values, divisor, f)

[wolfflow]

Thanks =)

[raimohanska]

The change is in master now. Is good? Should we publish this in readme too?

[wolfflow]

Yes of course, and if I get it right there was a mistake in code above: the last string of it must look like :

.withDescription(Bacon, "repeatedlyOnFrame", values, divisor)

[raimohanska]

Yes. That would look better.

[phadej]

This will definitely help with https://github.com/baconjs/bacon.js/issues/319 as well

[raimohanska]

Added documentation: https://github.com/baconjs/bacon.js#observable-withdescription