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

Help: improve Buffer:alloc bufnum arg description #3219

Merged
merged 7 commits into from Nov 4, 2017

Conversation

Projects
None yet
6 participants
@patrickdupuis
Contributor

patrickdupuis commented Oct 1, 2017

See discussion in #3211.

@snappizz snappizz added the comp: help label Oct 1, 2017

@snappizz snappizz added this to the 3.9 milestone Oct 1, 2017

@patrickdupuis

This comment has been minimized.

Show comment
Hide comment
@patrickdupuis

patrickdupuis Oct 1, 2017

Contributor

This is sort of meant as a draft proposal. Feel free to propose changes, as well as point to other places in the Help that would require the same info.

Contributor

patrickdupuis commented Oct 1, 2017

This is sort of meant as a draft proposal. Feel free to propose changes, as well as point to other places in the Help that would require the same info.

@patrickdupuis

This comment has been minimized.

Show comment
Hide comment
@patrickdupuis

patrickdupuis Oct 1, 2017

Contributor

That's much better @snappizz. Thanks!

Contributor

patrickdupuis commented Oct 1, 2017

That's much better @snappizz. Thanks!

@jamshark70

This comment has been minimized.

Show comment
Hide comment
@jamshark70

jamshark70 Oct 1, 2017

Contributor

Is it documented anywhere exactly how buffer and bus numbers are allocated? The last sentence is not really clear to me (but I can't work on an alternative just now).

Part of the problem is that we have a bias toward documenting classes and methods, and against documenting concepts and usage patterns. The impulse is to fix this issue by updating method documentation, without explaining the underlying concepts... the bias at work.

I'm on mobile now, maybe later I'll play with it.

Contributor

jamshark70 commented Oct 1, 2017

Is it documented anywhere exactly how buffer and bus numbers are allocated? The last sentence is not really clear to me (but I can't work on an alternative just now).

Part of the problem is that we have a bias toward documenting classes and methods, and against documenting concepts and usage patterns. The impulse is to fix this issue by updating method documentation, without explaining the underlying concepts... the bias at work.

I'm on mobile now, maybe later I'll play with it.

@muellmusik

This comment has been minimized.

Show comment
Hide comment
@muellmusik

muellmusik Oct 5, 2017

Contributor

"highly unnecessary" is a bit too strong and I am not sure it is logical (can something be unnecessary to a certain degree?).

Hmm, I read that as highly discouraged, and unnecessary... but a comma would make that clearer. English is ambiguous here.

Optionally, an explicit buffer number can be specified. This intentionally bypasses the server's buffer allocator, so if you haven't reserved this buffer number, you may get unexpected collisions. Use at your own risk.

How about: Under normal usage this argument should be left as nil. Supplying a number bypasses the server's buffer allocator, which can lead to conflicts. See discussion of the allocator scheme here for more info.

Contributor

muellmusik commented Oct 5, 2017

"highly unnecessary" is a bit too strong and I am not sure it is logical (can something be unnecessary to a certain degree?).

Hmm, I read that as highly discouraged, and unnecessary... but a comma would make that clearer. English is ambiguous here.

Optionally, an explicit buffer number can be specified. This intentionally bypasses the server's buffer allocator, so if you haven't reserved this buffer number, you may get unexpected collisions. Use at your own risk.

How about: Under normal usage this argument should be left as nil. Supplying a number bypasses the server's buffer allocator, which can lead to conflicts. See discussion of the allocator scheme here for more info.

@patrickdupuis

This comment has been minimized.

Show comment
Hide comment
@patrickdupuis

patrickdupuis Oct 10, 2017

Contributor

Since we don't currently have documentation to point users towards, i've left out @muellmusik's last sentence. I added a comma after discouraged, and added in the which can lead to conflicts part. I've brought back @snappizz's suggested last sentence to replace the one that was a bit unclear.

Contributor

patrickdupuis commented Oct 10, 2017

Since we don't currently have documentation to point users towards, i've left out @muellmusik's last sentence. I added a comma after discouraged, and added in the which can lead to conflicts part. I've brought back @snappizz's suggested last sentence to replace the one that was a bit unclear.

@telephon

sorry to bother you!

Show outdated Hide outdated HelpSource/Classes/Buffer.schelp
Show outdated Hide outdated HelpSource/Classes/Buffer.schelp
@@ -18,9 +18,9 @@ subsection:: Buffer Numbers and Allocation
Although the number of buffers on a server is set at the time it is booted, memory must still be allocated within the server app before they can hold values. (At boot time all buffers have a size of 0.)

This comment has been minimized.

@telephon

telephon Oct 12, 2017

Member

I agree that the best wording was

"Under normal usage this argument should be left as nil. Supplying a number bypasses the server's buffer allocator, which can lead to conflicts. See discussion of the allocator scheme here for more info."

@telephon

telephon Oct 12, 2017

Member

I agree that the best wording was

"Under normal usage this argument should be left as nil. Supplying a number bypasses the server's buffer allocator, which can lead to conflicts. See discussion of the allocator scheme here for more info."

This comment has been minimized.

@patrickdupuis

patrickdupuis Oct 12, 2017

Contributor

We don't currently have a discussion of the allocator scheme anywhere in the Help to point to. Adding this last sentence would be a mistake.

@patrickdupuis

patrickdupuis Oct 12, 2017

Contributor

We don't currently have a discussion of the allocator scheme anywhere in the Help to point to. Adding this last sentence would be a mistake.

This comment has been minimized.

@telephon

telephon Oct 13, 2017

Member

yes, you are right about this last sentence. So in my perspective, the best would be:

"Under normal usage this argument should be left as nil. Supplying a number bypasses the server's buffer allocator, which can lead to conflicts."

@telephon

telephon Oct 13, 2017

Member

yes, you are right about this last sentence. So in my perspective, the best would be:

"Under normal usage this argument should be left as nil. Supplying a number bypasses the server's buffer allocator, which can lead to conflicts."

@brianlheim

This comment has been minimized.

Show comment
Hide comment
@brianlheim

brianlheim Oct 25, 2017

Member

ping

Member

brianlheim commented Oct 25, 2017

ping

@snappizz snappizz modified the milestones: 3.9, 3.9.x Oct 28, 2017

@patrickdupuis

This comment has been minimized.

Show comment
Hide comment
@patrickdupuis

patrickdupuis Nov 4, 2017

Contributor

@telephon ping!

Contributor

patrickdupuis commented Nov 4, 2017

@telephon ping!

@brianlheim

I think this is OK for now. personally, when I read "which can lead to conflicts," I would really like to know where I can go to learn more. Especially when the top of the file just says to "see .alloc". I guess there should be a file/paragraph somewhere explaining allocators, it sounds like there isn't one currently.

@patrickdupuis

This comment has been minimized.

Show comment
Hide comment
@patrickdupuis

patrickdupuis Nov 4, 2017

Contributor

I agree, there should be some info to point users towards. For now, this is probably fine. If it's not already the case, we should create an issue to remind ourselves to create a help file explaining the allocators.

Contributor

patrickdupuis commented Nov 4, 2017

I agree, there should be some info to point users towards. For now, this is probably fine. If it's not already the case, we should create an issue to remind ourselves to create a help file explaining the allocators.

@brianlheim brianlheim merged commit 75d0e91 into supercollider:3.9 Nov 4, 2017

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details

@patrickdupuis patrickdupuis deleted the patrickdupuis:topic/buffer_alloc_help_fix branch Nov 4, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment