[Flang] Move markdown files(.MD) from documentation/ to docs/

[sameeranjoshi]

Summary

Other LLVM sub-projects use docs/ folder for documentation files.
Follow LLVM project policy.

Modify documentation/ references in sources to docs/.
This patch doesn't modify to reStructuredText(.rst) file format.

[sameeranjoshi]

The docs still render on github.
See a more friendly version below.
https://github.com/Sameeranjoshi/llvm-project/tree/sam-move-md-to-docs/flang/docs

[DavidTruby]

LGTM

[sscalpone]

I think you missed one.

[sameeranjoshi]

In D85884#2218264, @sscalpone wrote:

I think you missed one.

I didn't find what did I miss.
@sscalpone Can you please point what is missing?

[sameeranjoshi]

Fix review comments.

flang/README.md

 # Flang
 
 Flang is a ground-up implementation of a Fortran front end written in modern
 C++. It started off as the f18 project (https://github.com/flang-compiler/f18)
 with an aim to replace the previous flang project
 (https://github.com/flang-compiler/flang) and address its various deficiencies.
 F18 was subsequently accepted into the LLVM project and rechristened as Flang.
 
 ## Getting Started
 
-Read more about flang in the [documentation directory](documentation).
-Start with the [compiler overview](documentation/Overview.md).
+Read more about flang in the [docs directory](docs).
+Start with the [compiler overview](docs/Overview.md).
 
 To better understand Fortran as a language
 and the specific grammar accepted by flang,
-read [Fortran For C Programmers](documentation/FortranForCProgrammers.md)
+read [Fortran For C Programmers](docs/FortranForCProgrammers.md)
 and
-flang's specifications of the [Fortran grammar](documentation/f2018-grammar.txt)
+flang's specifications of the [Fortran grammar](docs/f2018-grammar.txt)
 and
-the [OpenMP grammar](documentation/OpenMP-4.5-grammar.txt).
+the [OpenMP grammar](docs/OpenMP-4.5-grammar.txt).
 
 Treatment of language extensions is covered
-in [this document](documentation/Extensions.md).
+in [this document](docs/Extensions.md).
 
 To understand the compilers handling of intrinsics,
-see the [discussion of intrinsics](documentation/Intrinsics.md).
+see the [discussion of intrinsics](docs/Intrinsics.md).
 
 To understand how a flang program communicates with libraries at runtime,
-see the discussion of [runtime descriptors](documentation/RuntimeDescriptor.md).
+see the discussion of [runtime descriptors](docs/RuntimeDescriptor.md).
 
 If you're interested in contributing to the compiler,
-read the [style guide](documentation/C++style.md)
+read the [style guide](docs/C++style.md)
 and
-also review [how flang uses modern C++ features](documentation/C++17.md).
+also review [how flang uses modern C++ features](docs/C++17.md).
 
 ## Supported C++ compilers
 
 Flang is written in C++17.
 
 The code has been compiled and tested with
 GCC versions from 7.2.0 to 9.3.0.
 

flang/docs/ArrayComposition.md

-<!--===- documentation/ArrayComposition.md 
+<!--===- docs/ArrayComposition.md 
   
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   
 -->
 
 This note attempts to describe the motivation for and design of an

flang/docs/BijectiveInternalNameUniquing.md

 ## Bijective Internal Name Uniquing
 
 FIR has a flat namespace.  No two objects may have the same name at
 the module level.  (These would be functions, globals, etc.)
 This necessitates some sort of encoding scheme to unique
 symbols from the front-end into FIR.
 
 Another requirement is
 to be able to reverse these unique names and recover the associated
 symbol in the symbol table.
 
 Fortran is case insensitive, which allows the compiler to convert the
 user's identifiers to all lower case.  Such a universal conversion implies
 that all upper case letters are available for use in uniquing.
 
 ### Prefix `_Q`
 
 All uniqued names have the prefix sequence `_Q` to indicate the name has
 been uniqued.  (Q is chosen because it is a
 [low frequency letter](http://pi.math.cornell.edu/~mec/2003-2004/cryptography/subs/frequencies.html)
 in English.)
 
 ### Scope Building
 
 Symbols can be scoped by the module, submodule, or procedure that contains
 that symbol.  After the `_Q` sigil, names are constructed from outermost to
 innermost scope as
 
    * Module name prefixed with `M`
    * Submodule name prefixed with `S`
    * Procedure name prefixed with `F`
 
 Given:
 ```
     submodule (mod:s1mod) s2mod
       ...
       subroutine sub
         ...
       contains
         function fun
 ```
 
 The uniqued name of `fun` becomes:
 ```
     _QMmodSs1modSs2modFsubPfun
 ```
 
 ### Common blocks
 
    * A common block name will be prefixed with `B`
 
 Given:
 ```
    common /variables/ i, j
 ```
 
 The uniqued name of `variables` becomes:
 ```
     _QBvariables
 ```
 
 Given:
 ```
    common i, j
 ```
 
 The uniqued name in case of `blank common block` becomes:
 ```
     _QB
 ```
 
 ### Module scope global data
 
    * A global data entity is prefixed with `E`
    * A global entity that is constant (parameter) will be prefixed with `EC`
 
 Given:
 ```
     module mod
       integer :: intvar
       real, parameter :: pi = 3.14
     end module
 ```
 
 The uniqued name of `intvar` becomes:
 ```
     _QMmodEintvar
 ```
 
 The uniqued name of `pi` becomes:
 ```
     _QMmodECpi
 ```
 
 ### Procedures/Subprograms
 
    * A procedure/subprogram is prefixed with `P`
 
 Given:
 ```
     subroutine sub
 ```
 The uniqued name of `sub` becomes:
 ```
     _QPsub
 ```
 
 ### Derived types and related
 
    * A derived type is prefixed with `T`
    * If a derived type has KIND parameters, they are listed in a consistent
      canonical order where each takes the form `Ki` and where _i_ is the
      compile-time constant value. (All type parameters are integer.)  If _i_
      is a negative value, the prefix `KN` will be used and _i_ will reflect
      the magnitude of the value.
 
 Given:
 ```
     module mymodule
       type mytype
         integer :: member
       end type
       ...
 ```
 The uniqued name of `mytype` becomes:
 ```
     _QMmymoduleTmytype
 ```
 
 Given:
 ```
     type yourtype(k1,k2)
       integer, kind :: k1, k2
       real :: mem1
       complex :: mem2
     end type
 ```
 
 The uniqued name of `yourtype` where `k1=4` and `k2=-6` (at compile-time):
 ```
     _QTyourtypeK4KN6
 ```
 
    * A derived type dispatch table is prefixed with `D`.  The dispatch table
      for `type t` would be `_QDTt`
    * A type descriptor instance is prefixed with `C`.  Intrinsic types can
      be encoded with their names and kinds.  The type descriptor for the
      type `yourtype` above would be `_QCTyourtypeK4KN6`.  The type
      descriptor for `REAL(4)` would be `_QCrealK4`.
 
 ### Compiler generated names
 
 Compiler generated names do not have to be mapped back to Fortran.  These
 names will be prefixed with `_QQ` and followed by a unique compiler
 generated identifier. There is, of course, no mapping back to a symbol
 derived from the input source in this case as no such symbol exists.

flang/docs/C++17.md

-<!--===- documentation/C++17.md 
+<!--===- docs/C++17.md 
   
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   
 -->
 
 ## C++14/17 features used in f18

flang/docs/C++style.md

-<!--===- documentation/C++style.md 
+<!--===- docs/C++style.md 
   
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   
 -->
 
 ## In brief:

flang/docs/Calls.md

-<!--===- documentation/Calls.md
+<!--===- docs/Calls.md
 
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 -->
 
 ## Procedure reference implementation protocol

flang/docs/Character.md

-<!--===- documentation/Character.md
+<!--===- docs/Character.md
 
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 -->
 
 ## Implementation of `CHARACTER` types in f18

flang/docs/ControlFlowGraph.md

-<!--===- documentation/ControlFlowGraph.md 
+<!--===- docs/ControlFlowGraph.md 
   
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   
 -->
 
 ## Concept

flang/docs/Directives.md

-<!--===- documentation/Directives.md 
+<!--===- docs/Directives.md 
   
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   
 -->
 
 Compiler directives supported by F18
 ====================================
 
 * `!dir$ fixed` and `!dir$ free` select Fortran source forms.  Their effect
   persists to the end of the current source file.
 * `!dir$ ignore_tkr (tkr) var-list` omits checks on type, kind, and/or rank.

flang/docs/Extensions.md

-<!--===- documentation/Extensions.md 
+<!--===- docs/Extensions.md 
   
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   
 -->
 
 As a general principle, this compiler will accept by default and

flang/docs/FortranForCProgrammers.md

-<!--===- documentation/FortranForCProgrammers.md
+<!--===- docs/FortranForCProgrammers.md
 
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 -->
 
 Fortran For C Programmers

flang/docs/FortranIR.md

-<!--===- documentation/FortranIR.md 
+<!--===- docs/FortranIR.md 
   
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   
 -->
 
 # Design: Fortran IR

flang/docs/IORuntimeInternals.md

-<!--===- documentation/IORuntimeInternals.md
+<!--===- docs/IORuntimeInternals.md
 
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 -->
 
 Fortran I/O Runtime Library Internal Design

flang/docs/ImplementingASemanticCheck.md

-<!--===- documentation/ImplementingASemanticCheck.md 
+<!--===- docs/ImplementingASemanticCheck.md 
   
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   
 -->
 # Introduction
 I recently added a semantic check to the f18 compiler front end.  This document

flang/docs/Intrinsics.md

-<!--===- documentation/Intrinsics.md 
+<!--===- docs/Intrinsics.md 
   
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   
 -->
 
 # A categorization of standard (2018) and extended Fortran intrinsic procedures

flang/docs/LabelResolution.md

-<!--===- documentation/LabelResolution.md 
+<!--===- docs/LabelResolution.md 
   
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   
 -->
 
 # Semantics: Resolving Labels and Construct Names

flang/docs/ModFiles.md

-<!--===- documentation/ModFiles.md 
+<!--===- docs/ModFiles.md 
   
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   
 -->
 
 # Module Files

flang/docs/OpenMP-4.5-grammar.txt

-#===-- documentation/OpenMP-4.5-grammar.txt --------------------------------===#
+#===-- docs/OpenMP-4.5-grammar.txt --------------------------------===#
 #
 # Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 # See https://llvm.org/LICENSE.txt for license information.
 # SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 #
 #===------------------------------------------------------------------------===#
 
 # OpenMP 4.5 Specifications

flang/docs/OpenMP-semantics.md

-<!--===- documentation/OpenMP-semantics.md 
+<!--===- docs/OpenMP-semantics.md 
   
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   
 -->
 
 # OpenMP Semantic Analysis

flang/docs/OptionComparison.md

-<!--===- documentation/OptionComparison.md 
+<!--===- docs/OptionComparison.md 
   
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   
 -->
 
 # Compiler options

flang/docs/Overview.md

-<!--===- documentation/Overview.md 
+<!--===- docs/Overview.md 
   
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   
 -->
 
 # Overview of Compiler Phases

flang/docs/ParserCombinators.md

-<!--===- documentation/ParserCombinators.md 
+<!--===- docs/ParserCombinators.md 
   
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   
 -->
 
 ## Concept

flang/docs/Parsing.md

-<!--===- documentation/Parsing.md 
+<!--===- docs/Parsing.md 
   
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   
 -->
 
 The F18 Parser

flang/docs/Preprocessing.md

-<!--===- documentation/Preprocessing.md 
+<!--===- docs/Preprocessing.md 
   
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   
 -->
 
 Fortran Preprocessing

flang/docs/PullRequestChecklist.md

-<!--===- documentation/PullRequestChecklist.md 
+<!--===- docs/PullRequestChecklist.md 
 
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 -->
 
 # Pull request checklist

flang/docs/RuntimeDescriptor.md

-<!--===- documentation/RuntimeDescriptor.md 
+<!--===- docs/RuntimeDescriptor.md 
   
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   
 -->
 
 ## Concept

flang/docs/Semantics.md

-<!--===- documentation/Semantics.md 
+<!--===- docs/Semantics.md 
   
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   
 -->
 
 # Semantic Analysis

flang/docs/f2018-grammar.txt

-#===-- documentation/f2018-grammar.txt -------------------------------------===#
+#===-- docs/f2018-grammar.txt -------------------------------------===#
 #
 # Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 # See https://llvm.org/LICENSE.txt for license information.
 # SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 #
 #===------------------------------------------------------------------------===#
 
 R0001 digit -> 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9

flang/docs/flang-c-style.el

-;;===-- documentation/flang-c-style.el ------------------------------------===;;
+;;===-- docs/flang-c-style.el ------------------------------------===;;
 ;;
 ;; Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 ;; See https://llvm.org/LICENSE.txt for license information.
 ;; SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 ;;
 ;;===----------------------------------------------------------------------===;;
 
 ;; Define a cc-mode style for editing C++ codes in Flang.

flang/lib/Evaluate/intrinsics.cpp

 using namespace Fortran::parser::literals;
 
 namespace Fortran::evaluate {
 
 class FoldingContext;
 
 // This file defines the supported intrinsic procedures and implements
 // their recognition and validation.  It is largely table-driven.  See
-// documentation/intrinsics.md and section 16 of the Fortran 2018 standard
+// docs/intrinsics.md and section 16 of the Fortran 2018 standard
 // for full details on each of the intrinsics.  Be advised, they have
 // complicated details, and the design of these tables has to accommodate
 // that complexity.
 
 // Dummy arguments to generic intrinsic procedures are each specified by
 // their keyword name (rarely used, but always defined), allowable type
 // categories, a kind pattern, a rank pattern, and information about
 // optionality and defaults.  The kind and rank patterns are represented