Consider reordering and reorganizing sections

[BillWagner]

Moving a couple ideas from an email thread here so we don't lose them

Currently the material for properties & indexers is organised as follows:

§15.7 Properties -> §15.7.2 Static and instance properties
Specification of properties
§15.7.3 Accessors -> §15.7.6 Virtual, sealed, override, and abstract accessors
Specification of accessors, shared by both properties and indexers. 15.7.3, 15.7.4 & 15.7.6, added by PR 837, have Notes explaining they are shared as they are written in terms of properties (by happenstance 15.7.5 is written in terms of both)
§15.8 Events
Specification of events
§15.9 Indexers -> §15.9.2 Indexer and Property Differences
Specification of indexers. 15.9.2 was added in PR 837 to bring the differences together at the end of 15.9

This is a bit mixed up and a little bit of shuffling may help. Having shared material being in subclauses of 15.7 seems wrong to me, but even just swapping Events & Indexers around so similar material is adjacent would help. Here is one possible shuffle:

§15.7 Properties -> §15.7.2 Static and instance properties
Specification of properties
§15.8 (prev 15.9) Indexers -> §15.8.2 (prev 15.9.2) Indexer and Property Differences
Specification of indexers
§15.9 Accessors
§15.9.1 General
The content of what is currently Notes on 15.7.3, 15.7.4 & 15.7.6
§15.9.2 (prev 15.7.3) Accessors -> §15.9.5 (prev 15.7.6) Virtual, sealed, override, and abstract accessors
Specification of accessors, shared by both properties and indexers.
§15.10 Events
Specification of events

And related note:

We currently define most aspects of all member function kinds in the Classes chapter, and enhance/restrict a few of those in the Structs chapter, and then again to a lesser extent in the Interfaces chapter. Coming soon in V8, we’ll be looking at PR #681, which adds support for default member function member implementations in interfaces for pretty much all member function kinds. As you will see from some of the proposed edits in that PR, I tried to deal with having the core definition of each given function member kind in the Classes chapter, and then amending/extending it in the others.

Taking this idea into account, does it make sense to put all the core member function details in a “Member functions” chapter, and have the Classes, Structs, Interfaces chapters point there, with each containing only supplemental information?

[BillWagner]

@jskeet

I think we should decide if we want to do some of this work during the Pre-8 milestone.

[jskeet]

Yes, it would be good to get as much of this as we feel we can bite off done before we start applying new features. Let's talk about it at the meeting.

[RexJaeschke]

I thought about this a great deal as I was spec'ing PR #681. I finished up putting at the start of each section in the Classes chapter that introduced a new member kind, words to the effect that this description covers classes and structs, but the interfaces chapter had more to say.

From a cleanliness pov, pulling the core stuff in a separate chapter, "Member Functions" as Bill suggested, sounds like a fine idea. At the start of each member function section we could have a fixed-template-style statement something like:

This feature is supported by classes/structs/interfaces [[include those, as appropriate]]. The following description is augmented and/or constrained by its parent type in sections xx, yy, ..., and zz.

From a less-ideal pov, this would involve some non-trivial effort, the result of which would need some serious review to make sure errors were not introduced.

FYI, despite MS proposal's suggesting that a (V9) record is a new type, after discussion with Mads I've spec'd it as a qualified class type and in V10, a qualified struct type, so the reordering under discussion is not impacted by the addition of records.

While it's fine to discuss this as a Pre-V8 topic, I don't see that it should hold up V8 work.

[jskeet]

Nigel is going to look at just the reordering aspect to see how feasible it is.
Bill will look for duplicated text for more information to feed into a discussion.