Your hostility toward an MIT licensed project is what is ruining the open-contribution model of developing software. In 2005, it was "Hey, this looks great, want me to write up a documentation?" Now it's "Not up to my standards, it's a joke." Absolutely disgusting behavior that is becoming gradually more common.
_UI_EXTERN const char *uiInit(uiInitOptions *options);
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.
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
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.
Hobby or personal-interest projects with an expectation of no real use don't need externally-facing documentation because they have no externally-facing APIs at all, not because their APIs are obvious.
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.
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).
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.
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.
Open source contribution happens when the contributor has invested themself in the project and wants to maintain the relationship. Perhaps the requester is evaluating multiple packages and wants to inform the project why they're going with another one instead. Maybe they got to the point in their evaluation that they're ready to commit only to discover a critical issue hidden in the (lack of) documentation.
It also comes off as hostile since implies that the requester's time is less valuable than the project maintainer's. Perhaps the requester is busy contributing to other open source projects. Perhaps the requester only has time right now to use the software, but has the goal of contributing in the future.
The project's maintainer's responsibility is maintaining the software, presumably because of some personal interest. Reporting and even expecting them to fix issues is absolutely normal.
It is. In large projects, there are relatively few maintainers responsible for evaluating the requests, reports and code from lots of people. They're scarce resources.
https://www.youtube.com/watch?v=fMeH7wqOwXA https://www.slideshare.net/linaroorg/maintainer
The main benefit is that it forces one to try to be professional and consistent, and to avoid being flippant, cryptic, didactic, and condescending.
Keep in mind that cutting customers loose is a natural part of the game, too. If someone demands to get a Big Mac at Chipotle there's no law that says they get to block the line for eternity.
geofft doesn't have an "issue" because he's not using the library; he can avoid the non-documentation problem for himself quite adequately by ignoring the library and moving to a different one.
> If you can answer those questions,
No you can't. You can only reverse engineer what the code does, not what the programmer intended.
Why would I sit there reverse engineering someone's code to write a document for them which codifies the bugs they didn't intend to make? They will just reject the doc "oh, thanks for writing this but that's not what's supposed to happen; that's a bug. Can you wait until next release and then change your document based on the new code? Thanks.".
Fuck that, you know?
Will the designer even take the document seriously going forward? Or will he just regard that as someone else's unimportant opinion about what a particular revision of his program did once upon a time?
We already know something about the designer's attitude is toward documentation, from the lack of it.
Satellite documentation: different story. I mean, tutorials, guides to internals and things like that. But, no, I'm not writing the basic, fundamental spec for your undocumented code you've already written.
I agree with this position. I am also working on my own open-source projects, as well as other projects that I know have conscientious maintainers and a high-quality community. Why should I contribute my time to this project?
To be a little blunt: if this project has not thought about things like ownership of pointers and concurrency safety, it is not a project I think other people should use. My time is limited, and I use it on improving projects that I think are worth improving.
> 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.
As an open-source maintainer, this doesn't describe me at all. I care more about things that improve the world than things that amuse me. (I also work on a few things that amuse me, but they're relatively clear about that status, and f they're not, I welcome someone calling me out on it.) All the long-term projects I work on are motivated by wanting that project to be a healthy project available as a compelling option for as many people as possible.
I had the rather delightful experience of starting a new job recently and finding that the next team over had just decided to start using a project I've been maintaining for a few years. If I had not spent time writing both code and documentation that welcomed unknown future users, this would never have happened. (And I still have not written nearly enough documentation for it!)
If my motivation were just filling my own needs, I probably wouldn't publish software at all. If it were that plus bolstering my personal brand, it would go on my blog or as CC-BY-NC-ND or something. My entire motivation for releasing software under a free license is for other people to use it.
I work on several personal projects whenever I have free time and feel like programming. I keep them on private repositories because I don't think they are ready for publication. I'm not sure if they're ever gonna be ready.
The only issue I see with the parent comment is that it's a bit harsh. But it's good advice to someone "trying to get better at their craft": writing software, especially one intended to be used by others, without documentation, is generally poor practice. It's not entitled at all, as far as I can see: it's not saying "I should have documentation for this project I use for free"–as far as I'm aware, they're not even using it at all. They're just evaluating whether as an interesting project they might want to take a look at later.
Let's just stay realistic: this guy is not selling a product, he's coding up something out of his own interest and is showing it to the world on github. I'm sure his interest in coding this up is much greater than his interest in writing documentation, so why should he focus on the latter? "So that anybody else can use his stuff" comes to mind as a first answer, and that's fair enough. But maybe that hasn't been his foremost interest.
One aspect that I see here is that with all the different language bindings, we're not talking about a documentation that would be trivial to write. I could imagine that an effort like that requires a lot of subtle changes to the API as more functionality is added which makes keeping the documentation up-to-date a tedious and quite hard thing to do -- so something that isn't a lot of fun. And isn't fun the main reason hobby projects get started on github in the first place?
I see your point that the current state of the project makes it very hard to use for you. Fair enough. But maybe it can become interesting again in the future when more documentation has been added -- perhaps even though the help of others. After all, it's an open source project.
So OK maybe I can get some insight reading the code. The "common" folder seems a good place to start[2]. Um, no. Short, generic uninformative filenames ("matrix.c", "control.c") and very few introductory comments. The opposite of "literate programming".
[1] https://github.com/andlabs/libui/blob/master/doc/main
[2] https://github.com/andlabs/libui/tree/master/common