Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Public API of CoinSelection Module. #53

Merged
merged 18 commits into from
Apr 22, 2020

Conversation

jonathanknowles
Copy link
Contributor

@jonathanknowles jonathanknowles commented Apr 21, 2020

Related Issue

#18
#30

Summary

This PR makes a number of changes aimed at improving the public API and documentation:

  • Revises the overall structure of the documentation for the main CoinSelection module.
  • Uses OPTIONS_HADDOCK prune to hide internal functions from Haddock documentation.
  • Gives each error condition its own separate type. Advantages:
    • Parameters to errors can be named, making Show instances more informative.
    • The documentation for each error can be more informative, as it can be separated into paragraphs (rather than squashed into a table cell).
  • Removes user-defined validation. If a caller wishes to validate a generated CoinSelection, they can easily validate it themselves after calling selectCoins.

These will be omitted from generated documentation.
If the user wishes to perform validation, they can perform it after
calling `selectCoins`.
To `CoinSelectionInputLimit`.

Justification: the record now only provides this item.
This type holds all parameters required by a coin selection
algorithm.
This type holds all values returned by a `CoinSelectionAlgorithm`.
@jonathanknowles jonathanknowles self-assigned this Apr 21, 2020
Additionally, change the order in which coin selection types are
presested in the generated documentation.
@jonathanknowles jonathanknowles force-pushed the jonathanknowles/module-structure-and-docs branch from 468af7f to 49de122 Compare April 22, 2020 03:59
This is for consistency with naming elsewhere.
@jonathanknowles jonathanknowles changed the title WIP: Module Structure and Documentation Module Structure and Documentation Apr 22, 2020
@jonathanknowles jonathanknowles marked this pull request as ready for review April 22, 2020 09:24
This has two advantages:

1. We can give field names to error parameters.
2. There's more documentation space to explain each error condition.

This change also adds documentation for each error condition that links
back to types defined in the CoinSelection module.
@jonathanknowles jonathanknowles force-pushed the jonathanknowles/module-structure-and-docs branch from c8c94d0 to 40f353d Compare April 22, 2020 09:38
@jonathanknowles jonathanknowles removed the request for review from paweljakubas April 22, 2020 09:41
@jonathanknowles jonathanknowles changed the title Module Structure and Documentation Structure and Documentation of CoinSelection module. Apr 22, 2020
@jonathanknowles jonathanknowles changed the title Structure and Documentation of CoinSelection module. Public API of CoinSelection Module. Apr 22, 2020
Copy link
Contributor

@rvl rvl left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sweet

src/library/Cardano/CoinSelection.hs Show resolved Hide resolved
src/library/Cardano/CoinSelection.hs Show resolved Hide resolved
src/library/Cardano/CoinSelection.hs Show resolved Hide resolved
src/library/Cardano/CoinSelection.hs Show resolved Hide resolved
src/library/Cardano/CoinSelection/Fee.hs Show resolved Hide resolved
src/library/Cardano/CoinSelection/Fee.hs Show resolved Hide resolved
Copy link
Contributor

@paweljakubas paweljakubas left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

very nice documentation pimping;-) great job!

@jonathanknowles jonathanknowles merged commit 40840da into master Apr 22, 2020
@jonathanknowles jonathanknowles deleted the jonathanknowles/module-structure-and-docs branch April 22, 2020 10:57
@jonathanknowles
Copy link
Contributor Author

@paweljakubas wrote:

very nice documentation pimping;-) great job!

Thanks for reviewing it!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants