another pass on documentation

Author: AntonLydike

mlir/include/mlir/Dialect/MPI/IR/MPIBase.td

@@ -17,13 +17,20 @@ def MPI_Dialect : Dialect {
   let description = [{
     This dialect models the Message Passing Interface (MPI), version 4.0. It is meant
     to serve as a targetable dialect, that can be lowered to multiple MPI implementations
-    and hide differences in ABI between these. The dialect models the functions of the MPI
+    and hide differences in ABI. The dialect models the functions of the MPI
     specification as close to 1:1 as possible while preserving SSA value semantics where it
     makes sense, and uses `memref` types instead of bare pointers.
 
     This dialect is under active development, and while stability is an
     eventual goal, it is not guaranteed at this juncture. Given the early state,
     it is recommended to inquire further prior to using this dialect.
+
+    The current version of the dialect models a very limited part of the MPI Library,
+    often simplifying operations. This was a conscious decision that enables us to
+    incrementally add features as they are needed.
+
+    For an in-depth documentation of the MPI library interface, please refer to official documentation
+    such as the [OpenMPI online documentation](https://www.open-mpi.org/doc/current/).
   }];
 
   let usePropertiesForAttributes = 1;

mlir/include/mlir/Dialect/MPI/IR/MPIOps.td

@@ -23,8 +23,11 @@ def MPI_InitOp : MPI_Op<"init", [
   ]> {
   let summary = "Initialize the MPI library, equivalent to `MPI_Init(NULL, NULL)`";
   let description = [{
+    This operation must preceed most MPI calls (except for very few exceptions,
+    please consult with the MPI specification on these).
+
     Passing &argc, &argv is not supported currently.
-    Inspecting the return value (error code) is also not supported.
+    Inspecting the functions return value (error code) is also not supported.
   }];
 
   let assemblyFormat = "attr-dict";
@@ -40,7 +43,7 @@ def MPI_CommRankOp : MPI_Op<"comm_rank", [
   let summary = "Get the current rank, equivalent to `MPI_Comm_rank(MPI_COMM_WORLD, &rank)`";
   let description = [{
     Communicators other than `MPI_COMM_WORLD` are not supprted for now.
-    Inspecting the return value (error code) is also not supported.
+    Inspecting the functions return value (error code) is also not supported.
   }];
 
   let results = (outs
@@ -60,8 +63,12 @@ def MPI_SendOp : MPI_Op<"send", [
   ]> {
   let summary = "Equivalent to `MPI_Send(ptr, size, dtype, dest, tag, MPI_COMM_WORLD)`";
   let description = [{
+    MPI_Send performs a blocking send of `size` elements of type `dtype` to rank `dest`.
+    The `tag` value and communicator enables the library to determine the matching of
+    multiple sends and receives between the same ranks.
+
     Communicators other than `MPI_COMM_WORLD` are not supprted for now.
-    Inspecting the return value (error code) is also not supported.
+    Inspecting the functions return value (error code) is also not supported.
   }];
 
   let arguments = (ins
@@ -82,9 +89,13 @@ def MPI_RecvOp : MPI_Op<"recv", [
   ]> {
   let summary = "Equivalent to `MPI_Recv(ptr, size, dtype, dest, tag, MPI_COMM_WORLD, MPI_STATUS_IGNORE)`";
   let description = [{
+    MPI_Recv performs a blocking receive of `size` elements of type `dtype` from rank `dest`.
+    The `tag` value and communicator enables the library to determine the matching of
+    multiple sends and receives between the same ranks.
+
     Communicators other than `MPI_COMM_WORLD` are not supprted for now.
     The MPI_Status is set to `MPI_STATUS_IGNORE`, as the status object is not yet ported to MLIR.
-    Inspecting the return value (error code) is also not supported.
+    Inspecting the functions return value (error code) is also not supported.
   }];
 
   let arguments = (ins
@@ -105,7 +116,11 @@ def MPI_FinalizeOp : MPI_Op<"finalize", [
   ]> {
   let summary = "Finalize the MPI library, equivalent to `MPI_Finalize()`";
   let description = [{
-    Inspecting the return value (error code) is not supported.
+    This function cleans up the MPI state. Afterwards, no MPI methods may be invoked
+    (excpet for MPI_Get_version, MPI_Initialized, and MPI_Finalized).
+    Notably, MPI_Init cannot be called again in the same program.
+
+    Inspecting the functions return value (error code) is not supported.
   }];
 
   let assemblyFormat = "attr-dict";