[flang-commits] [flang] 7e7484a - [flang][docs] Document plugin limitations

[Andrzej Warzynski via flang-commits]

Author: Andrzej Warzynski
Date: 2021-09-21T08:51:12Z
New Revision: 7e7484a816a53d557c3b2444d8e3daa60eabcc7b

URL: https://github.com/llvm/llvm-project/commit/7e7484a816a53d557c3b2444d8e3daa60eabcc7b
DIFF: https://github.com/llvm/llvm-project/commit/7e7484a816a53d557c3b2444d8e3daa60eabcc7b.diff

LOG: [flang][docs] Document plugin limitations

This was extracted from the discussion on
https://reviews.llvm.org/D108283.

Co-authored-by: Kiran Chandramohan <kiran.chandramohan at arm.com>

Differential Revision: https://reviews.llvm.org/D109871

Added: 
    

Modified: 
    flang/docs/FlangDriver.md

Removed: 
    


################################################################################
diff  --git a/flang/docs/FlangDriver.md b/flang/docs/FlangDriver.md
index ca85eedcbb5d0..03f3e244831f3 100644
--- a/flang/docs/FlangDriver.md
+++ b/flang/docs/FlangDriver.md
@@ -398,3 +398,20 @@ example programs are built. This includes plugins that are in the
 `flang/example` directory and added as a `sub_directory` to the
 `flang/examples/CMakeLists.txt`, for example, the `PrintFlangFunctionNames`
 plugin. It is also possible to develop plugins out-of-tree.
+
+## Limitations
+Note that the traversal API presented here is under active development and
+might change in the future. We expect it to evolve as support for new
+language features are added. This document and the examples will be updated
+accordingly.
+
+The current `ParseTree` structure is not suitable for modifications. The
+copy constructors are not available and hence duplicating code might not be
+trivial. Please take this into consideration when designing your plugin. In
+particular, creating a transformation plugin will be noticeably harder than
+analysis plugins that just consume (rather than edit) `ParseTree`.
+
+Lastly, if `ParseTree` modifications are performed, then it might be necessary
+to re-analyze expressions and modify scope or symbols. You can check
+[Semantics.md](Semantics.md) for more details on how `ParseTree` is edited
+e.g. during the semantic checks.