[Mesa-dev] NIR documentation

[Rob Clark]

I guess current comments + docs connor posted would have mostly
substituted for current comments + liberal pinging of
cwabbott/jekstrand/etc on IRC for what I've done so far in converting
freedreno over to NIR + various random additions to tgsi_to_nir.. or
in other words I think what was missing in the comments was mostly
docs-level big-picture view to pull the pieces together..

from a quick look at the docs, a bit more coverage of deref chains
(ie. example of direct vs indirect deref chain) might be useful..
maybe a couple other things I missed, but so far docs + comments look
like a pretty big improvement over comments alone

BR,
-R


On Thu, Jun 4, 2015 at 7:22 PM, Timothy Arceri <t_arceri at yahoo.com.au> wrote:
> 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
>
>
> _______________________________________________
> mesa-dev mailing list
> mesa-dev at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/mesa-dev