5 ms·

I might be interested, esp. since it claims Python bindings, but documentation appears to be nil. Seriously, nonexistent. A GUI lib surely has an API complex en

by fernly 8y ago

I might be interested, esp. since it claims Python bindings, but documentation appears to be nil. Seriously, nonexistent. A GUI lib surely has an API complex enough to require _some_ kind of reference docs, at least. But the contents of the doc folder[1] are just a joke, most of the files contain single lines, and the .md files are fragments with many "TODO" notes. 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 https://github.com/andlabs/libui/blob/master/doc/main [2] https://github.com/andlabs/libui/tree/master/common https://github.com/andlabs/libui/tree/master/common

noobermin 8y ago
The readme specifically says it has no docs and asks users to look at the main header file.
krapp 8y ago
try the examples folder.
- saagarjha 8y ago
  That's nice, but falls quite short of proper documentation.
vortico 8y ago
The entire API is 1100 lines. https://github.com/andlabs/libui/blob/master/ui.h https://github.com/andlabs/libui/blob/master/ui.h You don't need a separate documentation for that. In fact, most functions have sufficient docstrings if their names don't fully describe their function. 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.
- stochastic_monk 8y ago
  With that many digits, uiPi should definitely have an L suffix.
  - andlabs 8y ago
    Except that would make uiPi a long double, whereas every drawing API in libui just takes a double. Now as to whether the drawing APIs should use long double instead of double, I don't know; I will say that both cairo and Quartz/Core Graphics use double, so... (And on Windows, Direct2D takes floats, so at least on that platform, it's probably not going to make a difference at all...)
- 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 ago
    Great! 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.
dman 8y ago
I find it a bit sad that this is the top comment. I have witnessed free software/OSS have tremendous amount of positive effect on the world, however as the years go by I can't help feeling that we have trained a generation of users to act in an entitled manner towards software that is free and often the labor of love of some fellow developer trying to get better at their craft.
- vortico 8y ago
  Definitely agree that this has started happening in the last ~10 years. The solution is to convince programmers to maintain their own open-source projects so they can discover for themselves the reasons developers do this. (e.g. it's not magic or altruism, there are real reasons.)
- kodablah 8y ago
  I view it a bit differently. I can't help feeling that we have trained a generation of devs to act in an entitled manner towards documentation that is easy and formerly seen as requisite as the code itself. Personally, I find documenting my projects a labor of love because it's where I can distill all of my hard work in a presentable format.
- behringer 8y ago
  I've been programming for a long time, but if it's undocumented I don't use it, period. It takes too much time, gets too buggy, and I can just write it myself and understand it completely (and document it as I go).
- saagarjha 8y ago
  > I have witnessed free software/OSS have tremendous amount of positive effect on the world, however as the years go by I can't help feeling that we have trained a generation of users to act in an entitled manner towards software that is free and often the labor of love of some fellow developer trying to get better at their craft 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.
tacostakohashi 8y ago
I have no doubt that the author would accept a patch should you see fit to contribute some documentation.
- saagarjha 8y ago
  Sure, but I hope you agree that I have no obligation to submit a patch, given that I'm not using this software, just as the author has no obligation to provide documentation for me either.
kleiba 8y ago
But let's be honest: how many people write up a really good documentation for their github project? I mean, something that actually adds substantial value on top of what the source code, code comments and examples programs can provide? And is not outdated, i.e., actually always in sync with the code portion of the project? I'm sure the answer is > 0, but I would be very astonished if the percentage would be a high double-digit number. 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.
jventura 8y ago
I'm maintaining the python bindings at https://github.com/joaoventura/pylibui/ https://github.com/joaoventura/pylibui/. Happy to accept pull requests for it..
billsix 8y ago
For imgui (https://github.com/ocornut/imgui/ https://github.com/ocornut/imgui/) and uklear (https://github.com/vurtun/nuklear https://github.com/vurtun/nuklear), docs are basically unnecessary. You just have to look at the examples/demos and copy pasta. Immediate mode GUIs are great.

by fernly 8y ago

noobermin 8y ago

The readme specifically says it has no docs and asks users to look at the main header file.

krapp 8y ago

try the examples folder.

saagarjha 8y ago
That's nice, but falls quite short of proper documentation.

vortico 8y ago

The entire API is 1100 lines. https://github.com/andlabs/libui/blob/master/ui.h https://github.com/andlabs/libui/blob/master/ui.h You don't need a separate documentation for that. In fact, most functions have sufficient docstrings if their names don't fully describe their function. 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.

stochastic_monk 8y ago
With that many digits, uiPi should definitely have an L suffix.
- andlabs 8y ago
  Except that would make uiPi a long double, whereas every drawing API in libui just takes a double. Now as to whether the drawing APIs should use long double instead of double, I don't know; I will say that both cairo and Quartz/Core Graphics use double, so... (And on Windows, Direct2D takes floats, so at least on that platform, it's probably not going to make a difference at all...)
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 ago
  Great! 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.

dman 8y ago

I find it a bit sad that this is the top comment. I have witnessed free software/OSS have tremendous amount of positive effect on the world, however as the years go by I can't help feeling that we have trained a generation of users to act in an entitled manner towards software that is free and often the labor of love of some fellow developer trying to get better at their craft.

vortico 8y ago
Definitely agree that this has started happening in the last ~10 years. The solution is to convince programmers to maintain their own open-source projects so they can discover for themselves the reasons developers do this. (e.g. it's not magic or altruism, there are real reasons.)
kodablah 8y ago
I view it a bit differently. I can't help feeling that we have trained a generation of devs to act in an entitled manner towards documentation that is easy and formerly seen as requisite as the code itself. Personally, I find documenting my projects a labor of love because it's where I can distill all of my hard work in a presentable format.
behringer 8y ago
I've been programming for a long time, but if it's undocumented I don't use it, period. It takes too much time, gets too buggy, and I can just write it myself and understand it completely (and document it as I go).
saagarjha 8y ago
> I have witnessed free software/OSS have tremendous amount of positive effect on the world, however as the years go by I can't help feeling that we have trained a generation of users to act in an entitled manner towards software that is free and often the labor of love of some fellow developer trying to get better at their craft 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.

tacostakohashi 8y ago

I have no doubt that the author would accept a patch should you see fit to contribute some documentation.

saagarjha 8y ago
Sure, but I hope you agree that I have no obligation to submit a patch, given that I'm not using this software, just as the author has no obligation to provide documentation for me either.

kleiba 8y ago

But let's be honest: how many people write up a really good documentation for their github project? I mean, something that actually adds substantial value on top of what the source code, code comments and examples programs can provide? And is not outdated, i.e., actually always in sync with the code portion of the project? I'm sure the answer is > 0, but I would be very astonished if the percentage would be a high double-digit number. 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.

jventura 8y ago

I'm maintaining the python bindings at https://github.com/joaoventura/pylibui/ https://github.com/joaoventura/pylibui/. Happy to accept pull requests for it..

billsix 8y ago

For imgui (https://github.com/ocornut/imgui/ https://github.com/ocornut/imgui/) and uklear (https://github.com/vurtun/nuklear https://github.com/vurtun/nuklear), docs are basically unnecessary. You just have to look at the examples/demos and copy pasta. Immediate mode GUIs are great.