KT-58965 (Consider moving content of subsection 4.1.1.1 to chapter 5): Possible resolution

[MarkTheHopeful]

The reasons for and against are described in the corresponding issue on YouTrack.

[ice-phoenix]

To reiterate, the main question here is: where we should have the section and where we should have a reference to the section. Feel free to read the sections a bit more to get some more context and come up with an answer.

[ice-phoenix]

Do you think the path Inheritance > Inheriting > Inheritance delegation is the best to place the section about inheritance delegation within the Inheritance section?

I have a feeling Inheriting talks about smth else, and there is another better-suited section in Inheritance to talk about inheritance delegation.

[MarkTheHopeful]

Remark: here the "Inheritance delegation" section is not located in the "Inheriting" section, but rather as an independent section directly inside the "Inheritance" chapter.

Apparently, if we are still considering places within the "Inheritance" chapter, it may seem meaningful to move the section to the "Classifier type inheritance", as, well, it does speak about the classifiers, but as I see it, "Classifier type inheritance" is more general, talking about what can actually be affected by inheritance, rather than about specifics of how.
The next section, "Matching and subsumption of declaration" describes which declarations can be considered as "matching", and thus a section about one specific case of inheritance ("Inheritance delegation") cannot be placed here or before it.
Next comes the "Inheriting" section, which, to be honest, just expands on the previous section, again, talking about general rules for inheritance.
The only section left is "Overriding", which is the only section finally introducing overriding and showing concrete examples.

Perhaps it may be meaningful to put it after the "Overriding" section, especially since "Inheritance delegation" references it, and, as it seems, is even more specific.

[ice-phoenix]

I think I would prefer to place it right after the "Classifier type inheritance", tbh.

[ice-phoenix]

You made a great point in the issue, that this section is somewhere in between Inheritance and Declarations. One of the ways we use in the specification to reconcile such cases is to keep a forwards or backwards reference, saying "Well, actually we also have inheritance delegation, it is described in more detail [here][there]". So that the reader who comes to Declarations looking for inheritance delegation still can find the full description.

[ice-phoenix]

The main question to answer here is then: where should we have the actual section and where should we have the reference? In Declarations or in Inheritance? I would like you to think a bit more, make a decision and explain your reasoning.

[MarkTheHopeful]

On the one hand, it seems that the chapter Inheritance talks mainly about inheritance and redefinition rules, rather than specific cases, while Inheritance Delegation is a specific thing and syntax related to classifier declaration.
However, on the other hand, the previous location of Inheritance Delegation is hidden deep inside the class declaration and includes both the syntax for it (which is suitable for this chapter) and the inheritance logic with rules (which is more suitable for the chapter Inheritance). In addition, it uses some of the concepts presented later in the chapter Inheritance.

One simple solution in this case would be to somehow split the entire Inheritance Delegation section into two parts-one with syntax, an example (perhaps some technical details) in the Declarations chapter, where it is present right now, and another referring to the exact chapters and concepts from the section Inheritance could go to the Inheritance section itself. These two "parts" could be further connected to each other.

However, the most significant problem with this approach is that the section itself is quite small, and splitting it will result in two even smaller sections with incomplete information, and in order to understand one of them, the reader will need to read the other anyway.

If the "Split" approach is acceptable in this situation, then I would prefer it (even though how to do the splitting is a good question), as the section does not fully belong to either of the chapters.

[ice-phoenix]

Thanks! I also agree that the split would be quite difficult. I think that we should keep the body of the section in "Declarations" and simply create the same-named section with reference to it in "Inheritance". WDYT?

[MarkTheHopeful]

Sounds good to me, will do so.
How much should be put to the section in inheritance? Just a reference will be too little for a section, and, I think, even for a subsection. If duplicating information is fine, then I guess I can put two first paragraphs of the original subsection into the new one, with third being somewhere around "Technical details and examples can be found in ". Or even put only the first one along with a small syntax example and just a few sentences from the second one, along with the reference...

[ice-phoenix]

It can be very minimal, for example, we have this very short section: https://kotlinlang.org/spec/built-in-types-and-their-semantics.html#built-in-annotation-types =)

But feel free to propose a more suitable split or reference.

[ice-phoenix]

@MarkTheHopeful Could I ask you to proceed with the discussed changes, squash the fixups and force-push to your branch? Thanks!

[MarkTheHopeful]

@ice-phoenix Done, decided to go with a small one-sentence-subsection with a reference. Fixups squashed and force-pushed.

Is the wording I used fine? I think trying to add anything else will result in duplication of already existing information from the corresponding subsection in the Declarations chapter.

[ice-phoenix]

👍

[ice-phoenix]

Could you please rebase onto the updated develop once again?