Microsoft-ui-xaml: Add architecture documentation of controls

[chingucoding]

Proposal: Add architecture documentation of controls

Summary

Currently there is a lot of documentation on how to use controls, however there is little to no documentation on how a control works, making it harder to fix bugs and contribute to controls. We should add documentation (e.g. a README.md) to controls which explain how the control works internally.

Status of controls

| Control | Status |
| --- | --- |
| NavigationVIew | Finished |
| ColorPicker | @robloo is working on this control |

Rationale

• Complex controls are huge code bases and not easy to navigate through making it hard to fix bugs
• People who are unfamiliar with a control's code base can be overwhelmed when trying to contribute, especially with complex controls such as NavigationView or ItemsRepeater

Scope

| Capability | Priority |
| :---------- | :------- |
| Add documentation on the internal architecture of controls | Must |
| Explain common "flows" inside a control (e.g. selecting an item inside NavigationView) | Should |

Important Notes

A possible documentation "template" could be:

# NavigationView

The NavigationView ...

## Architecture

NavigationView consists of ItemsRepeaters renderin NavigationViewItems.
Every NavigationViewItem notifies the NavigationView whether it got invoked or selected. The NavigationView stores the selection model and informs NavigationViewItems when they got selected.

## Common flows

### Event flows

#### NavigationViewItemInvoked
1. NavigationViewItem gets invoked
2. NavigationView get's informed that an item was invoked
3. NavigationView raises ItemInvoked
4. NavigationView updates selection
5. NavigationView notifies the invoked NavigationViewItem about it's new selection state
6. NavigationView raises SelectionChanged


### UIA flows

#### SelectedItem
...

Ideally we would have this in every control's folder however for multiple controls, there won't be much to point out (e.g. SplitButton which essentially only has one flow). In "special cases", e.g. the CommonStyles project, the README would explain what the "CommonStyles" project is for.

Open Questions/Issues

This would require a lot of "initial" work as this needs to be written first. I would like to help with that if we deem that this is good in the long run.

When a control's API changes in a lot of cases, these documents need to be updated.

[ranjeshj]

@MikeHillberg @chigy @StephenLPeters as FYI. We currently have the specs repo and the docs site but I think this makes sense in the repo next to the code - would you agree ?

[Felix-Dev]

I would also prefer if we could start adding documentation to APIs at the top of their definition describing their purpose.

We could start with the public APIs as the documentation for those already exist on https://docs.microsoft.com and could simply be copied over. This would already be quite helpful to me as I've often found myself having to open the UWP documentation to get a good high-level grasp of the purpose of some APIs. For example, a public API like
https://github.com/microsoft/microsoft-ui-xaml/blob/78fa7f674364e7c3e0facd424760826d284296b6/dev/TreeView/TreeViewList.cpp#L321

would get a block comment at the top containing this information (general function and parameter description). I shouldn't be required to open the UWP documentation alongside the WinUI source code when trying to get a feeling for the code I'm looking at.

Then we have internal APIs like
https://github.com/microsoft/microsoft-ui-xaml/blob/78fa7f674364e7c3e0facd424760826d284296b6/dev/TreeView/TreeViewList.cpp#L705
which are completely undocumented. When I looked at the TreeView code to fix a bug, I first had no real clue what the IsContentMode() API was all about. Yes, it became clear after studying more code of the TreeView implementation, but the point here is a comment like Indicates whether the TreeView items are supplied as TreeViewNode objects or supplied by (data binding) a data source would have directly told me the purpose of this API. No longer would I be required then to study the TreeView implementation just to find out what the purpose of an API is.

While adding high-level documentation to existing (internal) APIs might be unrealistic for now due to WinUI 3, perhaps we could at least start writing these for new APIs to be added or whenever the existing APIs have to be revisited (for example in case of a bug fix)?

It would also be great if this documentation could be written in a way so that it will show up in VS like this:

[robloo]

This would be a good place to describe template parts and how they are used internally 😃

[mdtauk]

It would be nice to include a visual tree for the template parts - not sure how easy it would be to generate a visual diagram of this however - not without some effort in coding a custom documentation solution.

[chingucoding]

It would be nice to include a visual tree for the template parts - not sure how easy it would be to generate a visual diagram of this however - not without some effort in coding a custom documentation solution.

What exactly do you mean by "visual diagram" here? Where would this be better for you, compared to using the VisualTree helper/debugger that come with Visual Studio?

[mdtauk]

What exactly do you mean by "visual diagram" here? Where would this be better for you, compared to using the VisualTree helper/debugger that come with Visual Studio?

I meant for the documentation - if you are trying to explain how a control is "constructed" - is this not also a way to illustrate what makes the control's template and parts?

In the Live Document view, you get a TreeView of all the Xaml elements. This is the kind of thing I was thinking about.

[chingucoding]

Right, I see. Given that the source code would be directly next to the documentation, I am not sure how much of an improvement it would be to have that kind of information in there.

After all, the main goal is to provide documentation of the internal of the controls, information to make it easier to work on that control.

Explaining the (core) template parts and why they are needed is something we could definitely include.

[ranjeshj]

@chingucoding Thanks for opening this issue. Currently we have specs and docs. Both are targeted quite a bit towards the app developer consuming the feature. I think it makes a lot of sense to document the details to help WinUI contributors. This makes sense for architecture docs/details that would help someone contributing to the WinUI codebase and it makes sense to keep it next to the code - as opposed to usage documentation that is currently tracked in the docs site and in specs.

We could add a readme in the feature area folder or if we expect to add multiple files, we can create a 'docs' folder and put them there (so Navigationview\docs folder).

[chingucoding]

I think adding a Readme.md for the general control, and {Feature/Part}.md for specific areas is the best solution, that way it is easy to find the information you are looking for. What would be the next steps here @ranjeshj ?

[ranjeshj]

What would be the next steps here @ranjeshj ?

I think we can create this for one of the features as a start. Would you like to create a PR with some initial information? We can build it up as we go.

[chingucoding]

I think we can create this for one of the features as a start. Would you like to create a PR with some initial information? We can build it up as we go.

Sure thing! Any control, you would like me to start with ?

[ranjeshj]

NavigationView perhaps, since that looks like the motivation for this issue and is a complex control.

[chingucoding]

All right, I'll start working on the NavigationView documentation.