Enrich document with using getter function over state struct instance

[haoyang9804]

Inspired by this issue: #15525. I guess it's better to add a document for this special return type since it's truly confusing.

[github-actions]

Thank you for your contribution to the Solidity compiler! A team member will follow up shortly.

If you haven't read our contributing guidelines and our review checklist before, please do it now, this makes the reviewing process and accepting your contribution smoother.

If you have any questions or need our help, feel free to post them in the PR or talk to us directly on the #solidity-dev channel on Matrix.

[cameel]

Just a note on general structure here: the section on getters is already a bit too verbose IMO, with a lot of space and examples given to what are essentially obscure corner cases. I think we shouldn't make it even longer. We should consolidate the examples and make text more coherent. The focus should be kept primarily on explaining what getters are, the other things are just notes.

[haoyang9804]

Just a note on general structure here: the section on getters is already a bit too verbose IMO, with a lot of space and examples given to what are essentially obscure corner cases. I think we shouldn't make it even longer. We should consolidate the examples and make text more coherent. The focus should be kept primarily on explaining what getters are, the other things are just notes.

How about merging struct example and mapping example? They are all corner cases that can lead to confusion.

[cameel]

Yes, they should be consolidated IMO. We could have just one example showing them all. Or even just a general description of how the ABI for a getter looks like. Which is relevant e.g. when you want to override a function with a getter and should be mentioned too.

[haoyang9804]

Yes, they should be consolidated IMO. We could have just one example showing them all. Or even just a general description of how the ABI for a getter looks like. Which is relevant e.g. when you want to override a function with a getter and should be mentioned too.

Good suggestion. But I can only help with the consolidation part. I'm not very familiar with ABI.

[haoyang9804]

I think the Complex example is useful for benefit users' understanding in getter function. Maybe we can remove this example and only leave examples of array and struct the mitigate confusion.

[haoyang9804]

I think the Complex example is useful for benefit users' understanding in getter function. Maybe we can remove this example and only leave examples of array and struct the mitigate confusion.

I have merged the struct example and the array example. As for the Complex one that combine mapping and struct, since it implies no corner case, I removed it.
As for the ABI part, I think I can submit another pr after gaining some background.

[haoyang9804]

@cameel Hi Kamil, any suggestions on the new commit?

[matheusaaguiar]

I don't agree with the removal of the "complex example". It illustrates a case which we have to include, and which without mentioning it, the proposed added text of this PR would be incomplete.

The getter function of a struct returns a tuple whose elements are each individual struct member. But, as the complex example illustrates, in some cases they are omitted.
A simpler example would be the following:

contract C {
    struct S {
        int[2] a;
        uint256 x;
    }
S s;
}

In this case, a is omitted and the getter return type would be (uint256).

[haoyang9804]

Thx for your review @matheusaaguiar, I have refined the doc, please take a look

[matheusaaguiar]

I think this should stay.

[haoyang9804]

I have merged it with the ComplexStruct

[matheusaaguiar]

Not only arrays but also mappings don't have a getter generated (in this case) because as explained in the "Complex Example":
there is no good way to select individual struct members or provide a key for the mapping

Also, I guess that in the above quote, it was meant to be array members instead of struct members originally.

[haoyang9804]

have changed it

[matheusaaguiar]

Also, I guess that in the above quote, it was meant to be array members instead of struct members originally.

Can someone else check and see if they interpret it the same way I did? @r0qs @nikola-matic @clonker

[haoyang9804]

Hi @matheusaaguiar , is it OK to merge?