1313120 - Sort out developer documentation for Graphics

Status: NEW

(Core :: Graphics, defect)

Description

[George Wright (:gw280) (needinfo me!)]

One of the biggest hurdles I've identified to contributing to graphics code in Gecko is the lack of documentation. There's a lot of specialist knowledge about the code that exists only in people's heads, and a lot of non-obvious code flow that can be tricky to follow.

There is also quite a bit of documentation in the code, but it's not organised all that well, and can be tricky to find.

I'm looking into making this more accessible for people. I've certainly spent many days looking at the code and learning what's going on, and whilst I know it's not wasted time, it /feels/ like wasted time, especially if I don't use that knowledge to help break down the barriers for subsequent people.

This bug will serve as a tracking bug to look into what needs to be done here.

For starters, I'd like to:

- Start the doxygen doc autogeneration that Benoit Girard was maintaining. It no longer exists as it was on his people.mozilla.org which is now inactive.
- Look into how/where we can organise documentation within the tree, and potentially speak to other Gecko modules to see what they currently do.
- Determine documentation guidelines for patches incoming. In particular, I think documentation should address classes of questions concerning "why" something does something. "What" code does should be fairly obvious from method names, variable names, etc.

Comment 1

[George Wright (:gw280) (needinfo me!)]

https://wiki.mozilla.org/Platform/GFX/DesignDocumentationGuidelines is also a good resource that seems to have been ignored.

Comment 2

[BugBot [:suhaib / :marco/ :calixte]]

The bug assignee is inactive on Bugzilla, so the assignee is being reset.