Documentation could be misleading

[DanielDornhardt]

Hello!

Thank you for this fine library which ich making my life easier as it is right now, so I'm very happy :)

When i started working with my currencies right now I fell into a little trap:

I assumed currency.js would work a bit like moment.js, which also encapsulates some data to make it more easy to work with. Now moment() has it's own way of doing things, by always applying changes to the current date object, eg. moment().add(1, 'day').add(1, 'day').add(1, 'day') will give you a date three days from now buy it'll have modified the original moment() instance, so you need to clone it around with moment(someOtherMoment) before you do any changes if you want to keep the original moment around.

So far so good, you probably know that, and currency.js works differently, that's fine.

But the documentation (from https://currency.js.org/ ) seems to be a bit misleading in this regard, because for the methods the descriptions are written like this:(

currency.add( value )

Adds a string, number, or currency value to the current currency instance.

-> That to me implies that the current instance will be changed, which it won't do, it'll return a new instance with the new value.

I think rewording this slightly, or adding a few examples to the top how to work with multiple currency values and eg. add and multiply them together would be nice.

I'd love to help out but unfortunately I am scrambling to get my feature done at the moment, but I thought I'd leave this here as feedback + to show that people are happy using your library as well.

[Scotley]

Just a note that the documentation clearly states that it is immutable, and this is the expected functionality from an immutable library.

[scurker]

I think this is one of those things where I'm a little too close to the problem, but I do try to state up front that it's intended for the library to be immutable.

My intentions here were to show chainability of currency methods so that currency(1).add(2).add(3) would result in the return value being 6 while the original variable remains unmodified. I'm definitely open to having clearer documentation if you have some ideas.

[DanielDornhardt]

Hi, I'm gonna take some time and maybe try a suggestion / maybe some examples which would helped my specific case.

[mika76]

This has caught me out as well - I only really looked at the examples and did not really see the word "immutable" anywhere - so my suggestion would be to make some more examples.

[EDIT] I just actually did a search - the word "immutable" is found once in the github readme under features, and right at the bottom of the page under the title "Internationalization (i18n) and Formatting" at https://currency.js.org/ - so not totally easy to see.

Also there are things missing in the examples like comparisons on currencies (if currency(5) > currency(60)) - I currently have no idea how to do comparisons with this library...