search

idea4good / GuiLite

✔️The smallest header-only GUI library(4 KLOC) for all platforms
https://www.youtube.com/watch?v=grqXEz3bdC0
Apache License 2.0
7.42k stars 804 forks source link

Documentation? #49

Closed RecursiveDescent closed 3 years ago

RecursiveDescent commented 3 years ago

I really want to use this since I can't use Qt or wxWidgets and this looks like it would solve my problems. However, all I can find are some fairly complicated examples and images of code snippets with almost no context.

graysuit commented 3 years ago

@RecursiveDescent Did you bother to read this: https://github.com/idea4good/GuiLite#easy-to-learn-and-support

RecursiveDescent commented 3 years ago

I'm 14 days late but I meant like actual documentation on functions, their signatures, what they do etc. What's in the readme just throws a bunch of examples at you and assumes it shows you what the functions do. I was looking for something fast and that would work, so I didn't really have the time to be reading through the source to find the right functions to use.

graysuit commented 3 years ago

what I understand, your coding skills are weak. so you wanted a example which will build without errors instantly ?

install Visual studio 2017 with Desktop development with C++ . and open any *.sln file

arcanosam commented 3 years ago

I would like to add my 2 cents.

I think a good documentation is synonym to allowed more adoption of a technology.

It's OK not have enough time to do something better for your interested users, but you can't think too that everyone could have time to debug a project to learn or worst think that your interested users are 'weak' for don't do it.

Even if they don't have knowledge enough, the documentation it's for help them, even an advanced user could be helped.

I think great if we have more friendly documentation centered to the beginner user perspective, with levels of beginner, intermediate and advanced tutorials for example.

Everyone who joys programming, definitely will be thankful, would be great, but if not possible at moment, it's OK too.

As open-source project, I hope the community can collaborate one day at this subject

Sorry for reopen the thread.

Regards for all.

RecursiveDescent commented 3 years ago

what I understand, your coding skills are weak. so you wanted a example which will build without errors instantly ?

install Visual studio 2017 with Desktop development with C++ . and open any *.sln file

So, a javascript interpreter and operating systems development is weak? No, I simply did not have the time to sit there reading the code to figure it out, as many people do not feel like doing. I tried hard not to make this reply but I don't see what place what I understand, your coding skills are weak. has in a comment.

graysuit commented 3 years ago

@RecursiveDescent If you are js developer, then I know C/C++ is toughest for you. Actually, C requires highest programming skills. Whereas js doesn't develop much concepts like double,float,int32/64 ... etc. Even a declaring string is hard in C. Whereas js is too easy that good no. of developers are either js or py.

What are your assumption about GUI ? so that I can suggest better.

liangzelang commented 3 years ago

It's more friendly to users by providing APIs and detail func infos.

graysuit commented 3 years ago

right, and GUI-lite can't teach them programming. That's what author of this issue is looking for. lol

apalazzi commented 3 years ago

@graysuit documenting the complete API calls is part of a good documentation, and this project has none of this. Sure, it's not mandatory, but you can't expect developers to dive into the source code to find out which functions are available, what they do, the requested parameters, etc. And noone asked anybody to teach them programming, he just politely asked for some documentation.

graysuit commented 3 years ago

I just say politely it looks well documented to me due to:

Documentation also address which function do what and what parameters we should pass... https://github.com/idea4good/GuiLite/blob/master/documents/HowLayoutWork.md image

But still I think I'm human and can be wrong as well.

vectorselector commented 2 years ago

what I understand, your coding skills are weak. so you wanted a example which will build without errors instantly ?

install Visual studio 2017 with Desktop development with C++ . and open any *.sln file

Dearest Gray Suit, It does NOT matter about this programmers skill. they speak for mass adoption, they speak for being user-friendly, and you cannot be rationally opposed to this and so dismissive of documentation.

Do you consider documentation to be for weak amateurs!? It is actually the hallmark of professionalism. Competent domain authorities can explain domain concepts to outsiders in a clear and simple fashion. This person was suggesting something not merely to alleviate their personal laziness, but to make this library accessible to people who are not telepathic and make it look nice when someone or some company is choosing a GUI library. Documentation is an ASSET.

Documentation on most projects on Github need improvement.

I realize that this issue is closed, but I see this response and attitude demonstrated above as very shockingly counter-productive.

graysuit commented 2 years ago

@vectorselector I respect your opinion. Not sure why I look so harsh.

But you didn't read context. I replied to: I was looking for something fast and that would work, so I didn't really have the time to be reading through the source to find the right functions to use. and Fast food isn't digested. So simply I advised him to first learn VS with C++. Without it, even documentation can't help.

And about documentation, I know open source/free product will not grab your finger and make you visit all city. Traditionally, C/C++ developers need to figure out by themselves by unit testings and reading internal core. And even it have tons of samples, FAQ... Its new mindset of new non object oriented language programmers. Not C or C++.

  1. I agree. API usage documentation needed for guilite.h. Something a webpage like libvlc as example.
  2. Its not responsibility of guilite to explain what static libraries, .sh .bat scripts, headers do. Offcourse .sh/.bat scripts used for building via command line. Headers helps compiler in error raising. Headers just contain headings. The working code is inside libraries. (Atleast general cpp,headers,libraries,scripts knowledge is required by guilite)

and again. Don't think this rude or aggressive. This is my opinion, you may disagree or I may disagree with you. Hope you understand. Thanks

RecursiveDescent commented 2 years ago

By fast and would work, at the time I was referring to something easy to get working and simple to setup because I was working in an environment that I couldn't get something as fat as qt to work in, but for the advanced project I was going to use it for just some basic layout wasn't going to do it, and it was faster to just force qt to work than to wade through the header file(or tons of examples in separate repos) making my own map of everything as qt provides good enough documentation.

API usage documentation was exactly what I wanted, and for a project with 5.8k stars there was really no reason to still not have it.

and Fast food isn't digested. So simply I advised him to first learn VS with C++. Without it, even documentation can't help.

Also, autocompletion is not comparable with actual documentation... But that's also another reason why I needed documentation since I was working where I didn't have it in the first place even if I had the knowledge to intuition my way around the autocomplete suggested functions. After I got qt working I opened their documentation and that was it.

vectorselector commented 2 years ago

@vectorselector I respect your opinion. Not sure why I look so harsh.

But you didn't read context. I replied to: I was looking for something fast and that would work, so I didn't really have the time to be reading through the source to find the right functions to use. and Fast food isn't digested. So simply I advised him to first learn VS with C++. Without it, even documentation can't help.

And about documentation, I know open source/free product will not grab your finger and make you visit all city. Traditionally, C/C++ developers need to figure out by themselves by unit testings and reading internal core. And even it have tons of samples, FAQ... Its new mindset of new non object oriented language programmers. Not C or C++.

  1. I agree. API usage documentation needed for guilite.h. Something a webpage like libvlc as example.
  2. Its not responsibility of guilite to explain what static libraries, .sh .bat scripts, headers do. Offcourse .sh/.bat scripts used for building via command line. Headers helps compiler in error raising. Headers just contain headings. The working code is inside libraries. (Atleast general cpp,headers,libraries,scripts knowledge is required by guilite)

and again. Don't think this rude or aggressive. This is my opinion, you may disagree or I may disagree with you. Hope you understand. Thanks

I agree with your 2 points. I don't think you were being rude or aggressive, just dismissive, and I simply wanted to point out that documentation is considered good in the circles I run in. I totally understand if a personal project is indecipherable to outsiders but is provided "as-is" in the form of github archival, in the hopes that it's useful to others etc. I would say that a GUI library hoping for further adoption meets the criteria: "needs good documentation"

There's also the issue of a language or build-tool newbie not being a newbie programmer, but perhaps coming from other circles: It also doesn't cost much to add selective informative tips for newbies: Example:

To build, use the usual cmake convention: 1) mkdir build 2) cd build 3) cmake ..

How shall new users of cmake realize the conventions when the documentation emphasizes the total feature set of cmake rather than how most developers use it? We are culture-bearers as well. We are ambassadors of culture.

I realize that teaching what a shell is will be out of scope for documentation, but all necessary steps to build and arrive at hello-world or somesuch is what I consider the minimum acceptable documentation. If the API is really only defined in a single header file and is minimal as such, place comments and extract them for at least a minimal API document with function type signatures etc.