Documentation

[dcousens]

Just a stub issue, but we really need to start focusing on this.

[DrOfAwesomeness]

I have some time on my hands I could use to start documenting BitcoinJS if it would help. What do you want it documented with? JSDoc?

[dcousens]

I'm not sure how much value using JSDoc would give to this repository.
The biggest issue isn't understanding how to use the functions, but knowing which functions to use and when.

I think examples would be more beneficial at this point, because JSDoc is really only going to provide descriptions and type annotations, which we are often enforcing through src/types.js anyway.

Perhaps we can have a few users pipe in here what they feel would be the most beneficial? @williamcotton @thallium205 @juliustayl

@weilu thoughts?

[DrOfAwesomeness]

Yeah, you're right, the function names in BitcoinJS are generally self-explanatory. As a developer I've almost always found examples useful for learning a new library. I look forward to seeing some thoughts on this so I can help out a bit!

[dcousens]

We should definitely start collating some more examples here, and ideally get some input on what people would find the most helpful.

Right now, our README has the following examples:

• Generating a Bitcoin address
• Creating a [1:1 pubKeyHash] Transaction
• Creating a P2SH Multisig Address

I think we could do with some more examples around:

• OP_RETURN Transactions
• Custom output scripts
• nLockTime example

edit: I also see no reason why these examples couldn't all become integration tests in the test/integration folder.

[DrOfAwesomeness]

Should the examples be in an examples/ folder and in the test/integration folder? Or should they be added on to the end of README.md? Or should they only be in the test/integration folder?

[williamcotton]

I'll be happy to contribute to the OP_RETURN related tests and examples but I won't have any time until sometime next week.

[glorat]

As discussed on IRC, I think the most useful thing from you guys would be mini-examples of how to do things. Then put those examples in the integration tests section. Unit tests almost but don't quite cut it because they have full access to internal APIs that external consumers won't do, and you can run into odd issues like a client doing require('ecurve') themselves and finding they can't pass it into bitcoinjs - yes that is by design but it is not obvious.

One mini example that is obvious in bitcoinjs-lib 0.13 but not obvious is from Brainwallet

var hash_str = pad($scope.hash, 64, '0'); // A padded hex string from input to create a key from
var hash = hexToBytes(hash_str);
var eckey = new Bitcoin.ECKey(hash);

[dcousens]

Started adding these tests in the inttest branch.

[dcousens]

With the addition of example-like integration tests in #302, and links to them from the README. Did we have any priorities on what we wanted to document from here?

[dcousens]

Thoughts on an inline documentation format?

[jprichardson]

Thoughts on an inline documentation format?

"inline" as in a folder named "docs" or something like that right? You don't mean "inline" as in line with the code a la JSDocs, right?

[dcousens]

@jprichardson either or. I'd want the documentation to be as deterministic as possible, and not something we have to keep in sync.

[jprichardson]

something we have to keep in sync.

I'm of the school of mind that that's what it takes to produce quality software, however, I don't see any reason why this couldn't be automated to some degree.

I really despise inline documentation (inline with the code/ like JSDocs) as it really bloats source files. I wouldn't mind Flow comment annotations as that's at least useful and it would improve the quality of the software. I don't have any problem or issue with documenting tests though.

I have some thoughts on a building a tool to automate the process of building documentation. The number one principle of the tool would be that tests serve as the ultimate source of documentation, however expecting users of the library to dig into the test files is unreasonable. The main requirement of this tool would be to have a 'standard' sort of way to layout test files. Would changing the layout/renaming test files be something that you're opposed to?

[dcousens]

I really despise inline documentation (inline with the code/ like JSDocs) as it really bloats source files.

Agreed, but it can still be simpler than maintaining external documentation IMHO.

I wouldn't mind Flow comment annotations as that's at least useful and it would improve the quality of the software.

There only a few cases, namely around more complex classes such as TransactionBuilder that the "bloat" part of inline documentation would become painful.
For most of the code base, simply specifying the types and referencing behaviour from tests would be more than enough.

I have some thoughts on a building a tool to automate the process of building documentation. The number one principle of the tool would be that tests serve as the ultimate source of documentation, however expecting users of the library to dig into the test files is unreasonable. The main requirement of this tool would be to have a 'standard' sort of way to layout test files. Would changing the layout/renaming test files be something that you're opposed to?

What did you have in mind? This sounds intriguing, but, I'd rather not re-write our entire testing infrastructure for something experimental (both technically and socially).

[bhollan]

@dcousens @jprichardson
I actually would love to help with this. I have tons of time on my hands right now, I've worked with documentation a bunch at my last job, and I love the idea that the tests should show the way without having to dig through them.

[dcousens]

@bhollan did you have any ideas on how we could move forward?
I mean, we could easily settle on one thing and leave it at that, but it might be worth just a few more minutes discussion.

[bhollan]

@dcousens I sent an e-mail to @jprichardson to discuss his idea, but haven't heard back yet. We can discuss here if it would be better. Your response to his idea seemed favorable enough I assumed it was moving forward.
I really like underscore's side-by-side layout. http://underscorejs.org/docs/underscore.html
I think it should probably be easy enough to generate one document that is all the tests stitched together, and the another that is all the 'examples' with each test. There would be a bit of work to create a baseline of examples, but it would be pretty simple to upkeep after that. Just make an example every time a new test is created and re-run the script with every re-release.

I also like the loaclized examples on bootstrap. http://getbootstrap.com/css/
This would be a lot more work, but it's something.

I was thinking like a bitcoinjs.org/docs or /examples or something. I think it should be something that gets built from the test source code with every official release.

Just some thoughts.

[weilu]

How about whoever actually makes a PR gets to decide which doc format we use? ;) I'm happy to live with any inline doc format. Any doc is better than no doc.

[dcousens]

Agreed with @weilu. I'm happy to maintain it, but haven't got the time to spend researching the initial infrastructure at this time.