Standard for "since" tags in documentation
Closed this issue · 5 comments
When a change has been made to the behaviour of a function, should the since tag in the documentation be updated to the version which made the change or should the tag remain the version in which the function was first introduced?
I checked the haddock documentation and it stated either of the above as possibilities. I was wondering whether there was an agreed upon approach for this repository?
My overall approach would be:
- If we fixed a bug, no comment necessary
- If we changed the type, use the version the type changed at
- If we didn't change the type but changed the semantics, we screwed up
Ok I'm a little concerned that my situation is close to falling into category 3. I'm preparing an update to the yesod-form-multi package which adds delete buttons next to each generated field.
That means that the semantics of amulti and mmulti have changed and that the MultiSettings datatype that is passed to them has extra values in it. The MultiView which is returned by the aforementioned functions also has more values in it. So I guess in that respect the type has changed the problem is that the type changes are abstracted away because they occur inside the MultiSettings and MultiView data types.
It's probably not such a big deal, especially if the changelog states clearly that this is a change in the new version. I'm more concerned about subtly changing semantics deep in an API versus changes which will be blatantly obviously the first time someone runs the app.
Ok, I'll probably bump the since tag on MultiSettings and MultiView. Would you consider a change to these data structures to also be a change to the type of any functions that take / return them?
Probably not. It's subjective, and I don't feel strongly either way.