Skip to content
This repository has been archived by the owner on Mar 10, 2020. It is now read-only.

[WIP] jsdoc3 for docs #132

Closed
wants to merge 2 commits into from
Closed

[WIP] jsdoc3 for docs #132

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e9c3beb
try jsdoc
dignifiedquire Nov 21, 2015
fbd88a2
gulp docs task
dignifiedquire Nov 21, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
<a name="IpfsAPI"></a>
## IpfsAPI
**Kind**: global class

* [IpfsAPI](#IpfsAPI)
* [new IpfsAPI(host_or_multiaddr, port)](#new_IpfsAPI_new)
* [.add(files, opts, cb)](#IpfsAPI+add)

<a name="new_IpfsAPI_new"></a>
### new IpfsAPI(host_or_multiaddr, port)
Create a ipfs api


| Param | Type |
| --- | --- |
| host_or_multiaddr | <code>string</code> |
| port | <code>number</code> |

<a name="IpfsAPI+add"></a>
### ipfsAPI.add(files, opts, cb)
Add a file/many files to IPFS returning the hash and name. The
name value will only be set if you are actually sending a file.

**Kind**: instance method of <code>[IpfsAPI](#IpfsAPI)</code>
**Access:** public

| Param | Type |
| --- | --- |
| files | |
| opts | <code>object</code> |
| cb | <code>function</code> |

3 changes: 2 additions & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,8 @@
"test:node": "gulp test:node",
"test:browser": "gulp test:browser",
"lint": "gulp lint",
"build": "gulp build"
"build": "gulp build",
"docs": "jsdoc2md src/*.js > API.md"
},
"pre-commit": [
"lint",
Expand Down
26 changes: 21 additions & 5 deletions src/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,14 @@ const getRequestAPI = require('./request-api')
const Wreck = require('wreck')
const ndjson = require('ndjson')

exports = module.exports = IpfsAPI

module.exports = IpfsAPI

/**
* Create a ipfs api
* @constructor
* @param {string} host_or_multiaddr
* @param {number} port
*/
function IpfsAPI (host_or_multiaddr, port) {
const self = this
const config = getConfig()
Expand Down Expand Up @@ -35,8 +41,7 @@ function IpfsAPI (host_or_multiaddr, port) {

const requestAPI = getRequestAPI(config)

// -- Internal

/** @private */
function command (name) {
return (opts, cb) => {
if (typeof (opts) === 'function') {
Expand All @@ -47,6 +52,7 @@ function IpfsAPI (host_or_multiaddr, port) {
}
}

/** @private */
function argCommand (name) {
return (arg, opts, cb) => {
if (typeof (opts) === 'function') {
Expand All @@ -59,9 +65,19 @@ function IpfsAPI (host_or_multiaddr, port) {

// -- Interface

/** @public */
self.send = requestAPI

self.add = (files, opts, cb) => {
/**
* Add a file/many files to IPFS returning the hash and name. The
* name value will only be set if you are actually sending a file.
*
* @public
* @param {} files
* @param {object} opts
* @param {function} cb
*/
Copy link
Contributor

Choose a reason for hiding this comment

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

How does everyone feel about this JavaDoc'ization in order to have docs?

It is nice to have API docs, not sure if, since we have to write them anyway, if we prefer to right them on the readme with examples or add this to all of the function calls.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Pros

  • With the code
  • less chance of out of sync

Cons

  • looks like Java

Copy link
Contributor Author

Choose a reason for hiding this comment

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

ping @victorbjelkholm @RichardLitt

Copy link
Contributor

Choose a reason for hiding this comment

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

Jsdoc is pretty sweet, I just get annoyed at it because you end up with truly massive js files. It definitely helps out documentation, though, and I've used it before.

The only real con is that updating it can get old. but not as old as old docs.

Copy link
Contributor

Choose a reason for hiding this comment

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

my opinion: in general, while in other languages I do like godoc, i find that most successful modules I use in javascript are very small, easy to use, and have the docs/examples directly in the readme. i typically run away from jsdoc-ed modules.

this.add = (files, opts, cb) => {
if (typeof (opts) === 'function' && cb === undefined) {
cb = opts
opts = {}
Expand Down