The examples are long and confusing

[schrottkatze]

Hi, while trying to learn iced I've encountered the problem that the examples are really hard to understand, since they mostly seem to try to put all the code into a single file and just using inline modules.

For example the game_of_life example has a main.rs file which is >900 lines long, or the modal example with >450 lines. Both of these are extremely long and hard to understand because of that. Those are just two of the long and hard to understand examples.

Adding to that, another problem with understanding them is that they seem to completely lack proper documentation in the form of comments, which, coupled with the lack of an official tutorial (referring to the current state of the book which is a pile of TODOs).

These issues (among others) make it quite painful to properly learn to use iced, for me and probably quite some others.

[matidfk]

I agree with this, I struggled learning the subscription model. Some READMEs are missing completely, and some I think could do with a simple top level explanation in the readme instead of comments.

[hecrj]

$ tokei --type Rust --files examples/**/main.rs
==============================================================================================
 Language                           Files        Lines         Code     Comments       Blanks
==============================================================================================
 Rust                                  37         8386         7210           60         1116
----------------------------------------------------------------------------------------------
 examples/qr_code/src/main.rs                       75           62            0           13
 examples/websocket/src/main.rs                    172          146            0           26
 examples/stopwatch/src/main.rs                    137          116            0           21
 examples/tooltip/src/main.rs                       75           64            0           11
 examples/slider/src/main.rs                        63           51            0           12
 examples/svg/src/main.rs                           76           65            0           11
 examples/progress_bar/src/main.rs                  43           35            0            8
 examples/styling/src/main.rs                      164          145            0           19
 examples/sierpinski_triangle/src/main.rs          193          164            0           29
 examples/url_handler/src/main.rs                   71           60            0           11
 examples/modern_art/src/main.rs                   142          119            0           23
 examples/pokedex/src/main.rs                      222          187            0           35
 examples/pick_list/src/main.rs                    109           95            0           14
 examples/integration_opengl/src/main.rs           187          147           11           29
 examples/events/src/main.rs                       114           98            0           16
 examples/pane_grid/src/main.rs                    404          356            0           48
 examples/component/src/main.rs                    167          148            0           19
 examples/clock/src/main.rs                        155          128            0           27
 examples/system_information/src/main.rs           160          135            0           25
 examples/todos/src/main.rs                        607          519            3           85
 examples/lazy/src/main.rs                         251          227            0           24
 examples/counter/src/main.rs                       50           42            0            8
 examples/exit/src/main.rs                          71           61            0           10
 examples/download_progress/src/main.rs            199          176            0           23
 examples/scrollable/src/main.rs                   374          337            2           35
 examples/integration_wgpu/src/main.rs             289          229           18           42
 examples/color_palette/src/main.rs                463          387            2           74
 examples/arc/src/main.rs                          126          103            0           23
 examples/tour/src/main.rs                         672          611            2           59
 examples/multitouch/src/main.rs                   197          165            3           29
 examples/solar_system/src/main.rs                 225          188            0           37
 examples/geometry/src/main.rs                     210          175           10           25
 examples/custom_quad/src/main.rs                  159          141            0           18
 examples/custom_widget/src/main.rs                136          109            9           18
 examples/bezier_tool/src/main.rs                  242          209            0           33
 examples/modal/src/main.rs                        475          434            0           41
 examples/game_of_life/src/main.rs                 911          776            0          135

Most of the examples seem pretty short to me!

[matidfk]

I still think that better READMEs is a good cause; I might submit a PR with those soon

[schrottkatze]

I'd consider anything over 100-200 lines that are largely or completely undocumented too long for an example, and I still don't get why everything has to be in one file, the inline modules could at least be put in different files just so they're easier to navigate.

[hecrj]

I'd consider anything over 100-200 lines that are largely or completely undocumented too long for an example

I disagree. But in any case, I don't think undocumented code is automatically confusing or an issue. The length of a file isn't a good indicator of complexity either.

Instead of generalizing, could we talk specifics? Which are the confusing parts?

I still don't get why everything has to be in one file, the inline modules could at least be put in different files just so they're easier to navigate.

Easier to navigate is very subjective. If the examples are self-contained, they are easier to read and copy. There is no need to jump around between files to understand the different parts involved.

[Dot32Dev]

I do think the documentation in general should be improved

[schrottkatze]

100% agreed with that, good documentation is just as important as good code, and it certainly doesn't look good if a new developer looks at the iced book and sees nothing more then a bunch of TODOs, then at the examples and finds hundreds of lines of undocumented code, which could easily be split up to be made more readable.

The API documentation is... workable, but using iced just with it and the examples isn't a particularly pleasant experience, especially if there's no clear documentation on when to use which iced crate. Each time I tried to do something more advanced with iced then place a button on the screen I ended up trying to understand the examples, trying to use iced_aw (which is still outdated and you need to depend on the github repo so it works at all, and then themeing is still broken... yeah) and completely failing.

That coupled with the very confusing and verbose API isn't a particularly good learning experience, especially for people who are new to rust.

[hecrj]

it certainly doesn't look good if a new developer looks at the iced book and sees nothing more then a bunch of TODOs, then at the examples and finds hundreds of lines of undocumented code, which could easily be split up to be made more readable

We certainly know. We just don't care about "looking good" yet. iced is experimental software. You should not expect it to spoon-feed you or hand-hold you. There are rough, unpolished edges.

The API documentation is... workable, but using iced just with it and the examples isn't a particularly pleasant experience, especially if there's no clear documentation on when to use which iced crate. Each time I tried to do something more advanced [...]

I found this quite hyperbolic. Maybe iced isn't for you yet!

That coupled with the very confusing and verbose API isn't a particularly good learning experience, especially for people who are new to rust.

It'd be great if we talked specifics for once. What is confusing? What is verbose? I'd also argue that people that are new to Rust shouldn't use experimental libraries right away.