Page 1 of 1

Why does wxWidgets Documentation need to be so confusing?

Posted: Tue Mar 24, 2020 2:26 pm
by Nick
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?

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

Posted: Tue Mar 24, 2020 3:59 pm
by PB
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?

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

Posted: Tue Mar 24, 2020 7:46 pm
by Kvaz1r
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.

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

Posted: Tue Mar 24, 2020 8:19 pm
by Nick
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?

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

Posted: Tue Mar 24, 2020 9:09 pm
by PB
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.

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

Posted: Mon Mar 30, 2020 6:05 pm
by ONEEYEMAN
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.