[Mesa-dev] NIR documentation

[Timothy Arceri]

Nice, thanks Connor. I'm just spinning up on NIR now so look forward to
reading over it.

One thing I've notice about nir is the code comments are few an far
between which raises the learning curve a bit. Are there any plans to
pad this out a bit? Not suggesting you go do it all, more just wondering
if anyone else considers it important.

Tim

On Thu, 2015-06-04 at 17:51 -0400, Connor Abbott wrote:
> Hi,
> 
> Over the past few weeks or so, I've been sitting down and writing some
> documentation on how NIR, and especially the core NIR datastructures,
> works. At this point I think it's reasonably complete, although I've
> probably forgotten something that I should mention, and one thing
> that's missing for certain is a description of what the various
> lowering, optimization, and analysis passes do (although some of the
> motivation is covered in the documentation for other things). I could
> probably keep adding minor things to it, but at this point I think
> it's probably just better to put it out there. I haven't bothered to
> submit a patch, since it's probably easier to read the end-result than
> the source, although I've made a branch available at:
> 
> git://people.freedesktop.org/~cwabbott0/mesa nir-docs
> 
> and I've got a mirror of the generated output at:
> 
> http://people.freedesktop.org/~cwabbott0/nir-docs/
> 
> It's using Sphinx, which I chose since Rob said it worked well for
> him, and we have a similar use-case (mostly lots and lots of graphs,
> plus maybe a few equations and lots of text). The generated pdf is
> *mostly* ok, although I'm not really concerned about the rough edges
> -- just having an HTML page is enough for me. I'd like to put it on
> readthedocs.org, but for some reason it's not working for me since it
> seems to pick up the Gallium documentation despite pointing it to
> NIR's and then the page where it's supposed to go gives me a 404.
> 
> The intention is to merge this soon, and then when changing the parts
> of NIR that the docs refer to, it's on the author to update the docs.
> Of course, there's always the fear of the docs going stale, but I've
> tried to make it more about high-level information that you can't find
> in the source. Hopefully, if you're thinking about changing something
> fundamental about how NIR works, then the process of writing
> documentation will help you think through the change.
> 
> This is supposed to help people get up to speed on NIR, especially
> some of trickier parts of it like control flow, so if you're someone
> who learned it and found some parts confusing that aren't yet covered,
> then that would be very helpful.
> 
> Connor
> _______________________________________________
> mesa-dev mailing list
> mesa-dev at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/mesa-dev