Improve docs on functions

[danutsu]

While learning slint, I noticed that a lot of behaviors (in this case about functions) aren't clearly stated in the documentation. So I'm trying to document what I've learned and hopefully make it easier for the next person.

I've tested this mostly by experiment, meaning I'm not sure what's Working as Intended / by-design and what's Working as Implemented / by-chance. Actually that's a problem I'm hoping to address by documenting things more explicitly, but I need the core developers to tell me if something I've documented is not actually supposed to work that way.

Also, I don't know if you have specific standards/style regarding documentation that I should be following. If you do, let me know, I'm happy to read/apply them :)

There are more things I'd like to see in this file, in particular:

• typical use cases for functions
• more info/examples on how to use protected functions
• differences between functions and callbacks and guidance on when to use each

But I don't feel I know enough about these topics myself yet, so I'm starting with this.

[ogoffart]

The CI is failling in the doctests test which checks that the slint snippets in the documentation are valid. You need to mark them as ignored, or they need to import the right types

failures:

---- docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_125 stdout ----
thread 'docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_125' panicked at /home/runner/work/slint/slint/target/debug/build/doctests-1e236a2bc24032cd/out/test_functions.rs:480:568:
called `Result::unwrap()` on an `Err` value: "Unknown type VerticalBox"
stack backtrace:
   0: rust_begin_unwind
   1: core::panicking::panic_fmt
   2: core::result::unwrap_failed
   3: doctests::docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_125
   4: doctests::docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_125::{{closure}}
   5: core::ops::function::FnOnce::call_once
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

---- docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_16 stdout ----
thread 'docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_16' panicked at /home/runner/work/slint/slint/target/debug/build/doctests-1e236a2bc24032cd/out/test_functions.rs:456:215:
called `Result::unwrap()` on an `Err` value: "Parse error: expected a top-level item such as a component, a struct, or a global"
stack backtrace:
   0: rust_begin_unwind
   1: core::panicking::panic_fmt
   2: core::result::unwrap_failed
   3: doctests::docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_16
   4: doctests::docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_16::{{closure}}
   5: core::ops::function::FnOnce::call_once
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

---- docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_78 stdout ----
thread 'docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_78' panicked at /home/runner/work/slint/slint/target/debug/build/doctests-1e236a2bc24032cd/out/test_functions.rs:468:347:
called `Result::unwrap()` on an `Err` value: "Syntax error: expected ';'"
stack backtrace:
   0: rust_begin_unwind
   1: core::panicking::panic_fmt
   2: core::result::unwrap_failed
   3: doctests::docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_78
   4: doctests::docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_78::{{closure}}
   5: core::ops::function::FnOnce::call_once
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

---- docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_97 stdout ----
thread 'docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_97' panicked at /home/runner/work/slint/slint/target/debug/build/doctests-1e236a2bc24032cd/out/test_functions.rs:474:412:
called `Result::unwrap()` on an `Err` value: "Syntax error: expected ';'"
stack backtrace:
   0: rust_begin_unwind
   1: core::panicking::panic_fmt
   2: core::result::unwrap_failed
   3: doctests::docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_97
   4: doctests::docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_97::{{closure}}
   5: core::ops::function::FnOnce::call_once
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

---- docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_40 stdout ----
thread 'docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_40' panicked at /home/runner/work/slint/slint/target/debug/build/doctests-1e236a2bc24032cd/out/test_functions.rs:462:611:
called `Result::unwrap()` on an `Err` value: "Unknown type Button"
stack backtrace:
   0: rust_begin_unwind
   1: core::panicking::panic_fmt
   2: core::result::unwrap_failed
   3: doctests::docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_40
   4: doctests::docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_40::{{closure}}
   5: core::ops::function::FnOnce::call_once
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

failures:
    docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_125
    docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_16
    docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_40
    docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_78
    docsⳇreferenceⳇsrcⳇlanguageⳇsyntaxⳇfunctionsᐧmd::line_97

[danutsu]

Thanks! I fixed the tests (hadn't noticed them) and I reorganized things a bit to make things clearer. I also added a section on name resolution inside the function code, because I was a bit unsure about it myself -- I could see it being implemented both ways!

Please take another look :)

[danutsu]

Thank you, please take another look :smile:

[danutsu]

I wouldn't have put so much emphasis on the lookup.

The lookup rules were quite surprising to me as someone unfamiliar with Slint, and I'd say they are not very typical. I can't, off the top of my head, remember another language that works this way. If there was a page describing the lookup rules in general (perhaps I'll try to add that based on @ogoffart's comment) then yeah, this could be simplified :)

Thank you for the review :+1: -- let me know if anything else is needed before merging!