Wayland design and source code documentation

[Bryce Harrington]

On Thu, Dec 19, 2013 at 02:10:20PM -0800, Bryce Harrington wrote:
> On Thu, Dec 19, 2013 at 06:13:03PM +0300, Artsiom Anikeyenka wrote:
> > That's absolutely right and I realize that very well. But you need to think
> > of total newcomers (as I am). I like graphics and I decided to look around
> > how that stuff works nowadays under the hood. To have a big picture, before
> > I start implementing something on top of that. I don't know X11 and I don't
> > want to know it (it's being replaced why learn it). And what wayland
> > documentation provides is how wayland is going to replace X comparing both.
> > This is good for olders but how am I (and other newcomers) supposed to get
> > involved if I (they) want.
> > 
> > That's why I asked.
> >
> > Wayland is just another layer between subsystems. How does it communicate
> > with them? A simple picture showing wayland as a node of the graph of
> > subsystems (or just singly-linked list maybe) would be really-really
> > helpful because it would give a lot of info on what it is and why it's
> > there. With that in mind understanding the code would also be easier.
> > 
> > http://nouveau.freedesktop.org/wiki/IntroductoryCourse/ - this is a good
> > example of getting people involved.
> > 
> > Now I'm ready for starting to dig the code but it costed a lot of time.
> 
> Then perhaps one of the best things you could do, would be to write some
> docs.  You're still fresh at coming up to speed so probably know a lot
> better than the core devs what key questions other new developers would
> have, and probably have some opinions on how the docs should be
> composed.  Even if you're not 100% sure of all the technical details,
> just leave FIXMEs in the areas that need more detail, and others can
> fill in behind you.

I should add, I've found the devs very open to taking documentation
patches; it appears to be an easy way to get involved in the project.
(Just wish I had more time to pitch in...)

> Bryce
> 
> > On Wed, Dec 18, 2013 at 8:36 PM, Jasper St. Pierre <jstpierre at mecheye.net>wrote:
> > 
> > > Wayland has a lot of components: the code generator, the protocol, the
> > > client/server lib implementation, the design decisions we made to tie it
> > > all together. Yes, we aren't the greatest at documentation and we know that
> > > a lot is missing, but in general we assume experience with traditional
> > > toolkits, compositors/WMs, and in some cases, leftover knowledge from X11.
> > >
> > > There's also Weston, the de facto, most feature-complete, reference
> > > compositor. That has input management, output management, rendering,
> > > protocol implementations, clients, etc.
> > >
> > > In order for us to help you through the codebase and improve
> > > documentation, we sort of need to know what pieces you're interested in,
> > > and what you're having trouble understanding.
> > >
> > >
> > > On Wed, Dec 18, 2013 at 3:57 AM, Artsiom Anikeyenka <arty.anikey at gmail.com
> > > > wrote:
> > >
> > >> Hmmm, thanks, but I've seen those. I though maybe there is something
> > >> more. Ok I guess the good question will be:
> > >>
> > >> Do most of developers find it detailed and descriptive enough?
> > >>
> > >> I mean I'm still learning so maybe I just don't know enough to understand.
> > >>
> > >> Thanks, and have a very good day :)
> > >>
> > >>
> > >>
> > >> On Wed, Dec 18, 2013 at 2:02 AM, Bryce W. Harrington <
> > >> b.harrington at samsung.com> wrote:
> > >>
> > >>> On Tue, Dec 17, 2013 at 11:32:09PM +0300, Artsiom Anikeyenka wrote:
> > >>> > Hi guys,
> > >>> >
> > >>> > Is there a detailed documentation of wayland source code. Any good
> > >>> > visualization of the design? Are there any plans on adding/creating
> > >>> those?
> > >>> >
> > >>> > Thanks and be good.
> > >>>
> > >>> http://wayland.freedesktop.org/architecture.html
> > >>>
> > >>> http://wayland.freedesktop.org/docs/html/
> > >>>
> > >>> The former includes a couple block diagrams.
> > >>>
> > >>> The latter includes the client and server API's and the protocol
> > >>> specification, which are generated from the wayland codebases.
> > >>>
> > >>> Bryce
> > >>
> > >>
> > >>
> > >> _______________________________________________
> > >> wayland-devel mailing list
> > >> wayland-devel at lists.freedesktop.org
> > >> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
> > >>
> > >>
> > >
> > >
> > > --
> > >   Jasper
> > >