<div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Sep 12, 2019 at 9:50 AM David Greene <<a href="mailto:greened@obbligato.org">greened@obbligato.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex">Mehdi Amini <<a href="mailto:aminim@google.com" target="_blank">aminim@google.com</a>> writes:<br>
<br>
> The MLIR LangRef corresponds to the former part only, because this is what<br>
> is common to all dialects. On the other hand, each dialect will need to<br>
> provide its own LangRef equivalent (for example I linked to the Affine<br>
> dialect doc before).<br>
><br>
> Does it make sense?<br>
<br>
Yeah, it makes perfect sense.  I think maybe reading the document I got<br>
caught up in the BNF grammar -- it's a bit distracting.  I've not seen a<br>
similar BNF specification for LLVM IR.  It may exist somewhere, but BNF<br>
isn't part of any LLVM document I've read.  :) Maybe the grammar bits<br>
could be factored out into a formal specification and LangRef could be a<br>
little more informal.<br>
<br>
Just suggestions, obviously.</blockquote><div><br></div><div>That's a good one, we should look into outlining the grammar to make this more friendly to read.</div><div><br></div><div>Another things that I just remember now about documentation is that we don't expect dialects to write a "LangRef" that describe each operation. Instead we use a <a href="https://github.com/tensorflow/mlir/blob/master/g3doc/OpDefinitions.md#table-driven-operation-definition-specification-ods">table-driven approach for defining operation</a> and we generate both the C++ classes and the documentation from there (this helps keeping documentation up-to-date as well!).</div><div><br></div><div>From a local build directory of MLIR, you can try:</div><div><br></div><div>  {BUILD}/bin/mlir-tblgen -gen-op-doc {SRC}/Dialect/StandardOps/Ops.td -I {SRC}/include/ > std.md</div><div><br></div><div>(try --gen-op-defs and --gen-op-decls for the C++ code)</div><div><br></div><div>I pushed these here for your convenience: <a href="https://github.com/joker-eph/mlir-docs/">https://github.com/joker-eph/mlir-docs/</a><br></div><div><br></div><div>See for example the definition for alloc: <a href="https://github.com/tensorflow/mlir/blob/master/include/mlir/Dialect/StandardOps/Ops.td#L124" style="font-family:-webkit-standard">https://github.com/tensorflow/mlir/blob/master/include/mlir/Dialect/StandardOps/Ops.td#L124</a> </div><div>From there here is:</div><div>- the generated documentation: <a href="https://github.com/joker-eph/mlir-docs/blob/master/std.md#stdalloc-allocop">https://github.com/joker-eph/mlir-docs/blob/master/std.md#stdalloc-allocop</a><br></div><div>- the C++ class declaration for this operation: <a href="https://github.com/joker-eph/mlir-docs/blob/master/std.h#L130">https://github.com/joker-eph/mlir-docs/blob/master/std.h#L130</a></div><div>- and the implementation: <a href="https://github.com/joker-eph/mlir-docs/blob/master/std.cpp#L285">https://github.com/joker-eph/mlir-docs/blob/master/std.cpp#L285</a><br></div><div><br></div><div>Of course we need to improve the content in general, but I expect the incentive to do so to grow assuming we can get a space like <a href="http://llvm.org/mlir">http://llvm.org/mlir</a> ; at which point we could organize the MLIR overall online doc structure to include these generated file continuously.</div><div><br></div><div>Best,</div><div><br></div><div>-- <br></div><div>Mehdi</div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div>