Parcourir la source

Use "package directive" and "import directive" (#808)

These aren't really statements (because they're not executed at run time), and it's debatable whether they're declarations, since their primary purpose isn't to introduce a name. On Discord, "directive" seemed to be the consensus choice for an alternate term.
Geoff Romer il y a 4 ans
Parent
commit
e08beccc66
1 fichiers modifiés avec 13 ajouts et 12 suppressions
  1. 13 12
      docs/design/code_and_name_organization/README.md

+ 13 - 12
docs/design/code_and_name_organization/README.md

@@ -17,7 +17,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 -   [Details](#details)
 -   [Details](#details)
     -   [Source file introduction](#source-file-introduction)
     -   [Source file introduction](#source-file-introduction)
     -   [Name paths](#name-paths)
     -   [Name paths](#name-paths)
-        -   [`package` syntax](#package-syntax)
+        -   [`package` directives](#package-directives)
     -   [Packages](#packages)
     -   [Packages](#packages)
         -   [Shorthand notation for libraries in packages](#shorthand-notation-for-libraries-in-packages)
         -   [Shorthand notation for libraries in packages](#shorthand-notation-for-libraries-in-packages)
         -   [Package name conflicts](#package-name-conflicts)
         -   [Package name conflicts](#package-name-conflicts)
@@ -192,8 +192,8 @@ of `library` on the `package` of the code being imported.
 
 
 Every source file will consist of, in order:
 Every source file will consist of, in order:
 
 
-1. One `package` statement.
-2. A section of zero or more `import` statements.
+1. One `package` directive.
+2. A section of zero or more `import` directives.
 3. Source file body, with other code.
 3. Source file body, with other code.
 
 
 Comments and blank lines may be intermingled with these sections.
 Comments and blank lines may be intermingled with these sections.
@@ -212,11 +212,12 @@ IDENTIFIER(\.IDENTIFIER)*
 
 
 Name conflicts are addressed by [name lookup](/docs/design/name_lookup.md).
 Name conflicts are addressed by [name lookup](/docs/design/name_lookup.md).
 
 
-#### `package` syntax
+#### `package` directives
 
 
 ### Packages
 ### Packages
 
 
-The `package` keyword's syntax may be loosely expressed as a regular expression:
+The `package` directive's syntax may be loosely expressed as a regular
+expression:
 
 
 ```regex
 ```regex
 package IDENTIFIER (library STRING)? (api|impl);
 package IDENTIFIER (library STRING)? (api|impl);
@@ -245,8 +246,8 @@ Breaking this apart:
     under [libraries](#libraries). If it instead had `impl`, this would be an
     under [libraries](#libraries). If it instead had `impl`, this would be an
     implementation file.
     implementation file.
 
 
-Because the `package` keyword must be specified exactly once in all files, there
-are a couple important and deliberate side-effects:
+Because every file must have exactly one `package` directive, there are a couple
+important and deliberate side-effects:
 
 
 -   Every file will be in precisely one library.
 -   Every file will be in precisely one library.
     -   A library still exists even when there is no explicit library argument,
     -   A library still exists even when there is no explicit library argument,
@@ -256,7 +257,7 @@ are a couple important and deliberate side-effects:
 -   Every entity in Carbon will be in a namespace, even if its namespace path
 -   Every entity in Carbon will be in a namespace, even if its namespace path
     consists of only the package name. There is no "global" namespace.
     consists of only the package name. There is no "global" namespace.
     -   Every entity in a file will be defined within the namespace described in
     -   Every entity in a file will be defined within the namespace described in
-        the `package` statement.
+        the `package` directive.
     -   Entities within a file may be defined in
     -   Entities within a file may be defined in
         [child namespaces](#namespaces).
         [child namespaces](#namespaces).
 
 
@@ -303,7 +304,7 @@ Every Carbon library consists of one or more files. Each Carbon library has a
 primary file that defines its API, and may optionally contain additional files
 primary file that defines its API, and may optionally contain additional files
 that are implementation.
 that are implementation.
 
 
--   An API file's `package` will have `api`. For example,
+-   An API file's `package` directive will have `api`. For example,
     `package Geometry library "Shapes" api;`
     `package Geometry library "Shapes" api;`
     -   API filenames must have the `.carbon` extension. They must not have a
     -   API filenames must have the `.carbon` extension. They must not have a
         `.impl.carbon` extension.
         `.impl.carbon` extension.
@@ -312,7 +313,7 @@ that are implementation.
             be expected to be similar to a "Math/Algebra" library being in a
             be expected to be similar to a "Math/Algebra" library being in a
             "Math/Algebra.carbon" file path.
             "Math/Algebra.carbon" file path.
         -   The package will not be used when considering the file path.
         -   The package will not be used when considering the file path.
--   An implementation file's `package` will have `impl`. For example,
+-   An implementation file's `package` directive will have `impl`. For example,
     `package Geometry library "Shapes" impl;`.
     `package Geometry library "Shapes" impl;`.
     -   Implementation filenames must have the `.impl.carbon` extension.
     -   Implementation filenames must have the `.impl.carbon` extension.
     -   Implementation file paths need not correspond to the library name.
     -   Implementation file paths need not correspond to the library name.
@@ -425,8 +426,8 @@ implicitly.
 
 
 ### Imports
 ### Imports
 
 
-The `import` keyword supports reusing code from other files and libraries. The
-`import` keyword's syntax may be loosely expressed as a regular expression:
+`import` directives supports reusing code from other files and libraries. The
+`import` directive's syntax may be loosely expressed as a regular expression:
 
 
 ```regex
 ```regex
 import IDENTIFIER (library NAME_PATH)?;
 import IDENTIFIER (library NAME_PATH)?;