ExistentialAudio/SwiftOSC

Wiki

devinroth opened this issue · 19 comments

devinroth commented

Discussion about setting up a wiki.

devinroth commented

What I think we need is a detailed list of all the features of SwiftOSC with code.

Probably start with basic setup and examples of using each data type.

gwsounddsg commented

Agreed. I think it would be helpful to have several examples, as well as all the different queries you can make to check the status of either the client or server

gwsounddsg commented

One thing I found a bit jarring in getting started, was how simple this library is. Most I have used say it's so easy do x, y, and z. But in reality you have to do so many other things. I was expecting the same and got tripped up when it was just that simple.

But a detailed Wiki with a list of all properties and methods would be great. Also adding detailed comments that show Quick Help would be super helpful. eg:

/// Here's some details
func foo() {)

/**
  *A description field*
  - important: This is
    a way to get the
    readers attention for
    something.
 
  - returns: Nothing
 
  *Another description field*
  - version: 1.0
 */
func bar() {}
devinroth commented
gwsounddsg commented

Sounds good. What do you think is the best way to move forward?

One idea, we could each take one of the main classes (OSCServer and OSCClient) and add the quick help comments as a branch. Then we can review it and see the best of each pattern to come up with a design pattern. After that we could each attack a set of files while doing pull requests with code reviews into a branch (lets call it 1.4).

Thoughts?

devinroth commented

After giving it some thought, I think it will be better if I tackle the quick help and why don't you focus on the wiki. They can help inform the other.

I'll come up with a battle plan and what order to tackle things. and let you know.

gwsounddsg commented

Works for me.

One question, do you want the text in the quick help and the wiki to be the same? At least for the basic descriptions?

devinroth commented
gwsounddsg commented

Let's look at OSCClient as a for instance, specifically the send method (I'm thinking that for basic methods or types, we just use the triple '/' comment for the quick help):

/// Send an OSCElement, like an OSCMessage, to the client if connected.
open func send(_ element: OSCElement) {
    // code
}

That language says to me not only what it does, but tells the user basically how to use it. Chances are, they'd used this method with an OSCMessage. While OSCElement is the super class and totally valid code, the quick help cuts to the point of how someone will use it.

Also, note the "if connected". Telling the user there's a prerequisite for this to work. It could be more explicit like "if connected to a valid port and address". But I'm not sure that's necessary.

So in the Wiki, under this method it would have the exact same language as a description, and it would include an example and parameter description (with a link that that part of the wiki).

I use Appcode with the plugin Swiftlint. They recently did a Wiki for their rules, and I love the format. Check it out and let me know what you think.

devinroth commented

It sounds like you know what you're doing and I'm pretty busy with other stuff between this repo and BlackHole. So why don't you just go ahead and work on stuff and I'll just edit as I see fit. Your format looks good to me.

gwsounddsg commented

Sounds good to me. Would you mind creating a 1.4 branch? I'll use my fork to do changes, then do pull requests into that branch so you can code review it.

I'll start with the quick help, then move onto the wiki.

devinroth commented

Done.

gwsounddsg commented

Hey Devin,

Sorry I've been MIA. Had to travel for work and haven't been able to keep updating the quick help. I'm back now and should be able to keep working on it tonight.

devinroth commented

No worries. I just merged it so i can make some changes myself when i can.

lasaa2 commented

Until wiki is ready, can you support within this thread?

I has iPad project to communicate Behringer X32 digital mixer via OSC. First of all, thank you for your job with this library!

My questions related to send blob values. Unofficial document of x32 osc protocol says: "blobs (arbitrary binary data) follow specific rules depending on the section they apply to (see later in this document)"

For example: how to send "/‐prefs/haflags" command with SwitchOSC libary? Is it blob format?

How to use use Blob?

Document can be founded here: https://sites.google.com/site/patrickmaillot/x32
Topics to search: "/‐prefs/haflags" or "Protocol Parameters"

devinroth commented
lasaa2 commented

Hmm, can you form example command for me? I have research this a lot.

pekochun commented

I have a question.
What is following code?
Is this a concept close to the timeout value in UDP?

var bundle = OSCBundle(Timetag(secondsSinceNow: 0.016), message)

devinroth commented