6 ms·
I got to the first function in the API: _UI_EXTERN const char *uiInit(uiInitOptions *options); uiInitOptions is a struct that contains a single size_t Siz
by geofft 8y ago
I got to the first function in the API:
_UI_EXTERN const char *uiInit(uiInitOptions *options);
uiInitOptions is a struct that contains a single size_t Size. What's it the size of? Can I pass a NULL pointer? Does this function take ownership of the pointer, and if so, does it need to be allocated with malloc? If not, when can I free it - can I use a pointer onto my stack? Why does it take a non-const pointer - does the size (of whatever) change? What's the string that's returned? What's the lifetime of the string that's returned? Can another thread call uiInit, or does that break everything horribly? Or does it only break horribly if you don't copy the returned string first?
You don't need documentation, sure. But it's a good way to get users of the library that make wild assumptions so that you can no longer make reasonable upgrades to the library without breaking them, and that makes nobody (neither the library author, who wants people to use it, nor the users themselves, nor end users) happy.
- vortico 8y agoGreat! If you can answer those questions, send a pull request to add it to the docstring. You've spent some time thinking of those questions, so you'd write a very complete docstring. Complaining will not solve the issue. Sending a PR will solve it. This is what I was saying above. I am attempting to orient people into the "open-contribution" community, where we share the opinion that free software is NOT free to produce. Someone must do the things you are suggesting at some point if they are to exist, and who better than yourself? With regards to your last paragraph, a common misconception is that a "payment" of open-source software is number of users. That would be true for proprietary software where payment = number of users * price, but for open-source software the developers couldn't care less (except maybe superficially, but this mental reward is insignificant for the long-term motivation for a project). They want to make a library that solves their own problems and is stable. They allow people to help improve the library in exchange for releasing it for their unrestricted use. Otherwise, there is little motivation to release it. When I find a new library that solves a problem in an interesting way, I learn using whatever is available (existing documentation, headers, source, and examples) and write down the difficult parts. The price I pay for using the software is to send my notes back to the developers in a polished, organized form that is consistent with their existing documentation. Then, no one needs to repeat what I've done in the future.
- cyphar 8y agoWhile I agree with the general thrust of what you're saying (people should contribute far more to the free software they use rather than be angry with maintainers for not solving every issue under the sun -- and having more users is no substitute for having a few passionate external contributors), this is a fairly hostile way of trying to on-board people to a project. Not to mention that the developers that wrote the project in the first place are in a much better position to write documentation than anyone else (in the past I've had to review documentation from external contributors and I'm pretty sure it would've been phenomenally faster if I'd just written it in the first place -- it isn't their fault, it's just that I know the code and its history much better than them because I've maintained it).
- vortico 8y agoI agree that it's a somewhat hostile way to invite people to a project, but 1) I highly doubt that dropping a cheerful invite will have any convincing power other than someone replying "yeah, I should do that" and then promptly forgetting it, and 2) some scolding was needed. :) Your second point is a good one, but the developers are in a better position to write actual features and fix bugs than anyone else, and since documentation is more public-facing than source code, it's actually a better choice if someone wants to contribute anything at all, so the primary developers can spend their time more wisely. I certainly know the "phenomenally faster if I'd just written it in the first place" effect well, which is why I recommend to contributers to not do drive-by contributions but spend a good week writing notes while they use the library, and then convert to high-quality documentation, effectively adopting a section like you would with a community garden. Quality over quantity. And if the documentation attempt is low quality, it's still a much nicer way to prod the developer to write some documentation, so he/she can use it to define their quality standards or as a possible outline.
- saagarjha 8y ago> some scolding was needed Was it, really? I think the parent comments did a good job at pointing out a potential, actionable, flaw in this project. That doesn't mean that they should be "scolded" for pointing it out or that they themselves need to fix it.
- noobermin 8y ago>Does it take ownership of options, a struct with a single size_t. This is a bit extreme. My first thoughts (honestly) is yes, what is the size of. Following their advice to follow their examples, I looked at examples and it literally just zeros a uiInitOptions on the stack and sends it in. Thus I think it's something I wouldn't really need to care about usually. As for whether I need to worry about saving 8 bytes on the stack or elsewhere, that seems like such a rare question (amongst the questions people would have) that it would motivate digging a little bit. It took me probably 3 minutes to find the answer[0]. As someone said above, this is one cat's work in their free time. The gratuitous criticism is very unfair to them especially when you're worried about out circumstances most devs wouldn't have to deal with or care about. [0] https://github.com/andlabs/libui/blob/master/unix/main.c#L11 https://github.com/andlabs/libui/blob/master/unix/main.c#L11
- geofft 8y ago"Usually?" What are the unusual circumstances? Will I need to care about it at an inconvenient time two years later? I mean, yes, I can probably guess some things and end up with something that works with the current version of the library, but why would I choose this library to build on top of if I'm just guessing? The code cannot possibly answer the question of what changes the developers may make to the project in releases they consider backwards-compatible. My question is entirely about the API, not about the code itself.
- kleiba 8y ago...not to mention that this is obviously a work in progress. We're looking at a project's github page, not a product release page. I would think that like with a lot of coding projects, you start with an initial idea and see where it takes you, rather than with a full specification that you then follow. Given the limited resources of a single programmer, writing an extended documentation early on and then keeping it maintained with every chance to the architecture would be a huge burden, time and effort-wise. That's not to say it cannot be done, but I understand if you want to spend your time on coding first, if it's a pet project. There's nothing that prevents documentation to be added in the future.
- 8y ago
- Hello71 8y agoFor my sibling comments: http://www.catb.org/esr/writings/unix-koans/prodigy.html http://www.catb.org/esr/writings/unix-koans/prodigy.html