Why does wxWidgets Documentation need to be so confusing?

This forum can be used to talk about general design strategies, new ideas and questions in general related to wxWidgets. If you feel your questions doesn't fit anywhere, put it here.
Post Reply
Nick
Earned some good credits
Earned some good credits
Posts: 107
Joined: Thu Apr 11, 2019 12:50 am

Why does wxWidgets Documentation need to be so confusing?

Post by Nick » Tue Mar 24, 2020 2:26 pm

An example, starting with wxFrames, Default Constructor: docs.wxwidgets.org/trunk/classwx_frame. ... 78b8fe10fc
It is not exactly a Default because if I declare it does not work. Why don't you have an example right after the explanation? Wouldn't it be easier for those who are learning now?

Just below, This is not even a Syntax. Syntax mix with example of what should be put
wxFrame::wxFrame ( wxWindow * parent,
wxWindowID id,
const wxString & title,
const wxPoint & pos = wxDefaultPosition,
const wxSize & size = wxDefaultSize,
long style = wxDEFAULT_FRAME_STYLE,
const wxString & name = wxFrameNameStr
)

In short:
All the documentation is so confusing, without small examples that if they existed next to the information it would make it much easier for those who are starting, and would avoid millions of questions

Even the sample programs created by wxWidgets are extremely complex and confusing. See the wxTextCtrl. They put everything he can do in just 1 example, so anyone who is a beginner does not understand anything!

And all the beginner wants to know is how to put a controller on and he will never learn to do it in giant, complex code!

People who do not speak English as I do have 200 times more difficulty understanding this.

My case:
Instead of learning first with the documentation and then being able to do it in practice.
I'm learning in practice, asking in forums, creating the program, so I can learn to read the documentation.

That does not sound kind of bizarre?

PB
Part Of The Furniture
Part Of The Furniture
Posts: 2582
Joined: Sun Jan 03, 2010 5:45 pm

Re: Why does wxWidgets Documentation need to be so confusing?

Post by PB » Tue Mar 24, 2020 3:59 pm

For the record, I am not smart, my English is quite bad (it was my 4th language and I don't really speak it) as well but I generally never had problems understanding the documentation, I find it quite informative and usually get what I need.

As to your concrete examples. You do understand what a "default constructor" is, see e.g. here. The default constructor is used in wxWidgets when a two-step construction is required (constructor + Create())? So what exactly is the problem here?

As for "syntax", I have no idea what you mean by it. This is a constructor declaration and the meaning of all parameters is explained?

I have read a lot of wxWidgets documentation, so far I have not seen anything I would call bizarre.

The samples are indeed complex, often perhaps too much. I think they are just samples, not a step-by-step tutorial (which e.g. MFC had and wxWidgets does not): they show what wxWidgets is capable of. You need to start with baby steps, e.g. the minimal sample or Hello World from the docs and perhaps read the programmer guides. If you need something more linear, you will probably find some stuff on the internet, even the Book may be of some use, even when it quite outdated.

I think the actual issue may be, as you admitted yourself, your inability to understand technical English. You also seem to not understand C++ that well, and the code you posted before indicated that you do perhaps do not follow any general How to Write Good Code guidelines either. Sorry for being blunt.

Just curious, what C++ frameworks of similar complexity to wxWidgets are you experienced with and thought well of their documentation?

Kvaz1r
Filthy Rich wx Solver
Filthy Rich wx Solver
Posts: 231
Joined: Tue Jun 07, 2016 1:07 pm

Re: Why does wxWidgets Documentation need to be so confusing?

Post by Kvaz1r » Tue Mar 24, 2020 7:46 pm

Nick wrote:
Tue Mar 24, 2020 2:26 pm
Even the sample programs created by wxWidgets are extremely complex and confusing. See the wxTextCtrl. They put everything he can do in just 1 example, so anyone who is a beginner does not understand anything!
That's exactly the point. You can see and play with every single feature. Such samples are very good.
Nick wrote:
Tue Mar 24, 2020 2:26 pm
Instead of learning first with the documentation and then being able to do it in practice.
I'm learning in practice, asking in forums, creating the program, so I can learn to read the documentation.
Documentation is a reference and not a class book. It will be helpful when you became more familiar with wxWidgets and, maybe, C++. For learners there are several tutorials that should cover all basic user use cases. But it's open source and you can propose to extend it.

For the record - I'm also not native English speaker and never had trouble to understand what the documentation said.

Nick
Earned some good credits
Earned some good credits
Posts: 107
Joined: Thu Apr 11, 2019 12:50 am

Re: Why does wxWidgets Documentation need to be so confusing?

Post by Nick » Tue Mar 24, 2020 8:19 pm

I understand everything you two said above.
Yes, there are many tutorials scattered on the Internet, and most are obsolete. Even on the wxWidgets Wiki. And it confuses!

But I'm talking about making it easier! And if it is possible to do that, why not?

Look at this example: wiki.wxwidgets.org/The_Full_Implementat ... rame_Class

What is meant by FULL?
Beginners understand that full is complete. And not a piece of example. Why not put the complete full program, so that any beginner can compile, see how it works and understand the code?

Wouldn't it be easier if where you teach about it below you have an example of how to use it?
wxFrame::wxFrame ( wxWindow * parent,
wxWindowID id,
const wxString & title,
const wxPoint & pos = wxDefaultPosition,
const wxSize & size = wxDefaultSize,
long style = wxDEFAULT_FRAME_STYLE,
const wxString & name = wxFrameNameStr
)
Example of use:
new wxFrame(NULL, wxID_ANY, "Title", wxDefaultPosition, wxSize(400,300));
wxFrame *FrmMain = new wxFrame(NULL, wxID_ANY, "Title", wxDefaultPosition, wxSize(400,300), wxCLOSE_BOX|wxMINIMIZE_BOX);

What I mean is that it is very easy for a programmer who is accustomed to programming to understand, but it is not easy for those who are starting!
If there is documentation to explain, her goal would be to serve the largest possible target audience.

I'm not saying that the documentation for wxWidgets is bad. On the contrary, it is quite complete, allows download for offline consultation and etc ...
What really bothers me, Is it why not do better if it can be done?

PB
Part Of The Furniture
Part Of The Furniture
Posts: 2582
Joined: Sun Jan 03, 2010 5:45 pm

Re: Why does wxWidgets Documentation need to be so confusing?

Post by PB » Tue Mar 24, 2020 9:09 pm

First, wxWiki is not an official documentation, anyone (including you and me) can write anything there. Regarding the example you posted. I would say it actually is what is says it is: The Full Implementation Of The TextFrame Class. It does not say it is a full application.

Unfortunately, a lot of information on wxWiki is outdated or does not use what I would consider best practice. E.g., in the text you linked:
  • The ctor should use const wxString& for title instead of a pointer. Similarly with wxPoint and wxSize instead of ints. Why not mimic the ancestor API?
  • There is no reason to declare the menu-related member variables: They are never used.
  • I would advise against creating modal dialogs (in OnMenuFileOpen() and OnMenuFileSave()) on the heap, these are best created on the stack.
  • Using message maps is probably not a big issue, I have never used them, preferring more flexible Bind().
There are more things that could be perhaps be done better now.

Regarding the wxFrame ctor docs. It is unrealistic and unreasonable to expect that every method will have an example. What a method needs is a good description of what it does and meaning of its arguments. The programmer is expected to be capable of putting the pieces of information together and create a code doing what he wants. The official documentation has a tutorial on how to create the most basic application, see here. The "big picture" information is provided in the Overviews and I think one is supposed get familiar with relevant ones before getting serious about writing any code.

I do not think anyone ever said programming is easy. I am rather old and to be honest, I do not understand the currently popular belief that anyone and everyone could or even should be able to program computers. I learnt everything I know about computers by myself; I am not a programmer, just basically a hobbyist and I am fully aware I am incapable of being one. All I can do is very simple things. Thankfully, basic C++ and wxWidgets are very easy so even I can somehow accomplish what I want.

And last but not least
Nick wrote:
Tue Mar 24, 2020 8:19 pm
What really bothers me, Is it why not do better if it can be done?
wxWidgets is strictly a community project, with no company behind it. The developer resources are scarce and I believe can be used better than "improving" the documentation. What is "better" can be rather subjective and certainly, more does not always mean better. I, for one, would rather get my information quickly, without wading through a lot of low-density information texts which would just increase noise-to-signal ratio.

ONEEYEMAN
Part Of The Furniture
Part Of The Furniture
Posts: 4440
Joined: Sat Apr 16, 2005 7:22 am
Location: USA, Ukraine

Re: Why does wxWidgets Documentation need to be so confusing?

Post by ONEEYEMAN » Mon Mar 30, 2020 6:05 pm

Hi,
I think the OP is referring to the MSDN, where every possible WinAPI has an example of usage that is linked to the official API.
The ODBC documentation is done exactly the same way.

However, those are very specific APIs and when Microsoft wrote ODBC specifications it was pretty new and the programmers didn't know much about it.
So MS did a very fine job explaining how to write the ODBC application from the ground up.

I believe right now, all those examples should be removed from the official ODBC reference, because they don't do any good. And on top of that ODBC is seriously outdated.

All in all - documentation is not a place to put a sample code in. It just that - a documentation.
It should explain what the particular API does and (in case of OOP language/infrastructure/framework) what is the purpose of a specific class.

There should be place in documentation which will refer to the code sample(s) (which wxWidgets have).

About the complexity of the different samples.

Developers who comes here and try to work with wxWidgets should be familiar with the C++ (language and concepts). They should understand that the sample code is exactly what it is - the sample code that will demonstrate how to use a specific class.

Let's take you wxTextCtrl as an example. Would you expect to see 100 very small programs that will be broken like this:

- demonstrate the usage of read-only text control
- demostrate the usage of password text control
- demonstrate the usage of rich edit text control
etc etc tc

This is bizarre and unhelpful for multiple reasons.

Instead there is a one big wxTextCtrl sample that you should first compile and run, play with it, understand what wxTextCtrl can do and only then try to read the code for that sample. NOT VICE VERSA.

Now, I'm also not a native English speaker, but I've been around since 1980th. And I knew that I have to learn and understand English in order to become a decent programmer. Believe it or not - I actually learn the language by playing the "hack" and "LSL" series. and of course reading the books about C++ by K&R (translated to my native language though). And of course learning the language in school and university so that was not at all technical.

So all in all - I suggest to get beter with the language and get some C++ course at the local college.
Or u can try and learn python at the local college (this language is much easier to understand) and get acquainted with wxPython.

But you shuold get yourself comfortable with the English itself - first and foremost!!!

Thank you.

Nick
Earned some good credits
Earned some good credits
Posts: 107
Joined: Thu Apr 11, 2019 12:50 am

Re: Why does wxWidgets Documentation need to be so confusing?

Post by Nick » Mon May 11, 2020 1:15 am

I believe it's important to show it
I was looking for a way to erase the wxchoice control and to my surprise there is no explanation on how to do this in the wxWidgets documentation!
https://docs.wxwidgets.org/trunk/classwx_choice.html

But on another site it shows the existence of the Clear:
http://wxwindowsjp.osdn.jp/docs/html/wx ... hoiceclear

How could a person who is learning like me, who is starting out, for example on the wxWidgets Documentation Site discover the existence of this command? Because even finding out about it, I couldn't find any mention of the Clear command when trying to locate
https://docs.wxwidgets.org/trunk/search ... oice+clear

It seemed to me that at some point in the existence of wxWidgets there was such information to be copied by the site in question!

Also remembering that not even the Append Command is quoted. I don't even know where I learned about the existence of this command in wxChoice, but it wasn't in the documentation of wxWidgtes because there it is as if it never existed!

ONEEYEMAN
Part Of The Furniture
Part Of The Furniture
Posts: 4440
Joined: Sat Apr 16, 2005 7:22 am
Location: USA, Ukraine

Re: Why does wxWidgets Documentation need to be so confusing?

Post by ONEEYEMAN » Mon May 11, 2020 5:42 am

Hi,
What you should understand is that C++ is an OOP language.
Which means that sometimes the method might be documented inside the parent class. And there is no reason to duplicate.

Moreover, most of the IDEs currently on the market are capable of autocomplete.

Thank you.

Kvaz1r
Filthy Rich wx Solver
Filthy Rich wx Solver
Posts: 231
Joined: Tue Jun 07, 2016 1:07 pm

Re: Why does wxWidgets Documentation need to be so confusing?

Post by Kvaz1r » Mon May 11, 2020 7:02 am

Nick wrote:
Mon May 11, 2020 1:15 am
I believe it's important to show it
I was looking for a way to erase the wxchoice control and to my surprise there is no explanation on how to do this in the wxWidgets documentation!
https://docs.wxwidgets.org/trunk/classwx_choice.html
There is documentation for Clear in section Public member functions inherited from wxItemContainer.

Manolo
Can't get richer than this
Can't get richer than this
Posts: 713
Joined: Mon Apr 30, 2012 11:07 pm

Re: Why does wxWidgets Documentation need to be so confusing?

Post by Manolo » Mon May 11, 2020 5:45 pm

Nick, I know how you feel because I've felt the same. Let me share my experience here.

I'm not educated in programming, apart from a brief curse. I'm an engineer in a different branch. Despite of it, I always liked to code, and I did.

Many years ago I developed in Basic on DOS system. Everything was good and I released some good apps useful in my branch.
Then I met Basic limits, so I went ahead of C. Damn, pointers were a nightmare for me, but eventually I succeeded.
Then I faced my next improvement: Windows GUI. Again a wall. I had to read a lot about events, and when and how Windows sends them. I started with Win32 (base level) directly. It was hard for me to understand why such a simple window required so many code and parameters I didn't understand.
Then I saw many samples done in MFC which seemed a lot easier... but it was C++ code. No problem, I'm brave enough, let's move to C++.

Wow! C++ is quite a difficult beast to deal with quickly. There are plenty of new things compared to C or Basic. But the more I learnt the more I discovered its beauty power, mainly at writing complex applications.

So there I was, fighting C++, MFC and GUI, all at once. To get things worse, I realised I might incorporate to Linux world (a different beast). Linux handling is similar to Windows, but different enough to require more learning.
Happy idea: I just need how to draw a simple point or line or character, a few things more, and I can write my own code that would work both in Windows and Linux.
Naive idea. But pushed me, and after some short search I found wxWidgets.

wxWidgets saved my life. The code was much much much easy to understand that MFC. There were many features implemented a lot easier than MFC. I could write an app much more quickly.

The samples helped a lot. I was confident that what I was seeing was the way to code, so I worked hard to understand that code, follow its flow with the help of a debugger and realizing C++ things like an instance of an object deletes itself at the end of scope, or private/public access, or derived children do have many of their parents features, or overloading thing, or...or...or.

The point is that I was learning C++ and GUI by studying wx samples. It took time, of course. You need a more or less full-view of the picture to see how the details play.

Of course I read the documentation. I can say it's pretty good compared with most of API's docs out there.
But it's not the way to learn. Docs are not tutorials. They are not filled with examples because they already exist in the samples folder. I'd say it's more a feature-search. Or a quick way of remembering the parameters to use at that method you use right now...
You can also inspect the header for that class, if you know which file to look for. This is an advanced resource, and may confuse you more than enlighten you.

For example. Let's say I have a string and I want to append other string. I know I'm using wxString class, so I can search in its doc for something that looks like "append".
Or I have a control and I want to set my own background color. I look for 'background' or 'color' inside wxControl doc... and failed. Well, not that failed. The feature is hidden at wxWindow class. Next time I'll pay attention to parents and their public/protected methods.
More examples. Does wx provides some grid control? How wx deals with Unicode? Threading? OpenGL? Search the docs for these terms and likely you'll find what you wish.

Now you tell me, "Yes, good if you know the word to look for". You're right. Happens all the time in all life situations. Try with some synonyms. But the best is that you compile the sample, run it to see its features, and study the code to find out those names.

Finally, wxWidgets is pretty auto-explained code. The names in the methods and parameters are also self-explanatory.
Docs are more a reference. The samples show the features. Only some docs show some code example, just to serve as a support to understand the wording.

If you face wxWidgets (or any other C++ API) without a not-so-minimal knowledge of C++, man, you'll feel frustrated a lot of times. Be patient. You'll learn new things faster as you have more pieces of the puzzle.

Nick
Earned some good credits
Earned some good credits
Posts: 107
Joined: Thu Apr 11, 2019 12:50 am

Re: Why does wxWidgets Documentation need to be so confusing?

Post by Nick » Wed May 13, 2020 3:05 pm

Kvaz1r wrote:
Mon May 11, 2020 7:02 am
Nick wrote:
Mon May 11, 2020 1:15 am
I believe it's important to show it
I was looking for a way to erase the wxchoice control and to my surprise there is no explanation on how to do this in the wxWidgets documentation!
https://docs.wxwidgets.org/trunk/classwx_choice.html
There is documentation for Clear in section Public member functions inherited from wxItemContainer.
Thank you. This is helping me understand better about members.

Post Reply