search

Rantanen / node-mumble

Mumble client in Node.js
MIT License
155 stars 48 forks source link

Inconsistent Documentation #29

Closed timeDev closed 9 years ago

timeDev commented 9 years ago

The library documentation list events/attributes/methods that do not exist and also doesn't list ones that do. The examples of this I have found are User.moveToChannel() and Connection.on('user-move'). Please either update the docs to match the code or vice-versa.

Prior99 commented 9 years ago

Yes it is not up-to-date.

Rantanen commented 9 years ago

@Prior99, when you did the documentation, did you have a look at JSDoc or anything similar? Think it might be better to have the documentation derived from the code in the long run. Of course for stuff like events we'd then need to add more syntax in the code..

Rantanen commented 9 years ago

How would https://github.com/Rantanen/node-mumble/wiki/APIv2 look?

That's done using the jsdoc comments in the cec9e2db1bcce1c7116c3993073662c70b8c1a7d commit and jsdoc2md.

Didn't try documenting the events yet though so those are missing - and only tested on that one class.

Prior99 commented 9 years ago

I like it. No I didn't have a look at it, I wantes to have it done fast ;-) who likes to write documentation?

Rantanen commented 9 years ago

Working on this (because it's easier than the input streams which are a lot of work :p): e0d7d499932b6bf829a2e82066ff8d8066480889

Travis is under maintenance so wasn't able to push this there. Ideally in future it would be enough to land the documentation as JSDoc among the code and Travis build would push the documentation online to the wiki. Would let us document the functionality as we implement it instead of having to go to the wiki later to update it.

Prior99 commented 9 years ago

I like it.

johnrnelson commented 9 years ago

Allow me to say the documentation is not as good as the code. However, I'm loving that code so where does that leave us? :-)

Rantanen commented 9 years ago

The documentation is now generated from the JSDoc comments so it should be less outdated.

https://github.com/Rantanen/node-mumble/wiki/MumbleWrapper https://github.com/Rantanen/node-mumble/wiki/User https://github.com/Rantanen/node-mumble/wiki/Channel

Can't say whether the actual quality went up or down, but it should at least be easier to maintain while implementing new features now.

Prior99 commented 9 years ago

Wow. I love it. Thank you so much, writing doc is pain in the ass.

timeDev commented 9 years ago

Well then. Even though the new documentation is awesome, I still can't track users moving :( Closed.

bendem commented 9 years ago

Maybe the example here can help you? Though I agree it's not documented in User

timeDev commented 9 years ago

I already tried that, the event didn't seem to get fired...

2015-05-14 12:41 GMT+02:00 bendem notifications@github.com:

Maybe the example here https://github.com/Rantanen/node-mumble/wiki/MumbleWrapper#event-user- can help you? Though I agree it's not documented in User https://github.com/Rantanen/node-mumble/wiki/User

— Reply to this email directly or view it on GitHub https://github.com/Rantanen/node-mumble/issues/29#issuecomment-102000224 .

bendem commented 9 years ago

Just tried

connection.on('user-move', function(user, fromChannel, toChannel) {
    console.log('User ' + user.name + ' moved from channel ' + fromChannel.name + ' to ' + toChannel.name);
});

and it displayed User bendem moved from channel A to B as expected.

timeDev commented 9 years ago

Ok then maybe I had a typo or something... I will definately try this!

2015-05-14 12:50 GMT+02:00 bendem notifications@github.com:

Just tried

connection.on('user-move', function(user, fromChannel, toChannel) { console.log('User ' + user.name + ' moved from channel ' + fromChannel.name + ' to ' + toChannel.name); });

and it displayed User bendem moved from channel A to B as expected.

— Reply to this email directly or view it on GitHub https://github.com/Rantanen/node-mumble/issues/29#issuecomment-102002498 .