diff --git a/docs/README.md b/docs/README.md index d121a12f5fce..594bd946a752 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,4 +11,46 @@ These documents cover all aspects of Carbon ranging from the project down to detailed designs for specific language features. If you're trying to learn more about Carbon, we recommend starting at -/README.md. +[`/README.md`](/README.md). + +## Design + +The design of the Carbon language, and the rationale for that design, is +documented in the [`design/` directory](design/README.md). This documentation is +intended to support these audiences: + +- People who wish to determine whether Carbon would be the right choice to use + for a project compared to other existing languages. +- People working on the evolution of the Carbon language who wish to + understanding the rationale and motivation for existing design decisions. +- People working on a specification or implementation of the Carbon language + who need a detailed understanding of the intended design. +- People writing Carbon code who wish to understand why the language rules are + the way they are. + +This is in contrast to [proposals](/proposals/README.md), which document the +individual decisions that led to this design (along with other changes to the +Carbon project), including the rationale and alternatives considered. + +## Project + +The [`project/` directory](project/README.md) contains project-related +documentation for Carbon, including: + +- [goals](project/goals.md), and the + [principles](project/principles/README.md) and [roadmap](project/roadmap.md) + derived from those goals, +- how the project works, and +- how to contribute. + +## Guides + +The [`guides/` directory](guides/README.md) contains **to-be-written** end-user +documentation for developers writing programs in Carbon. + +## Spec + +The [`spec/` directory](spec/) contains the **to-be-written** formal +specification of the Carbon language. This is for implementers of compilers or +other tooling. This is intended to complement the interactive language explorer +tool (TODO: link). diff --git a/docs/design/README.md b/docs/design/README.md index ea985597efc7..cb3dfccc2f35 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -75,20 +75,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception ## Overview This documentation describes the design of the Carbon language, and the -rationale for that design. The goal is to provide sufficient coverage of the -design to support the following audiences: - -- People who wish to determine whether Carbon would be the right choice to use - for a project compared to other existing languages. -- People working on the evolution of the Carbon language who wish to - understanding the rationale and motivation for existing design decisions. -- People working on a specification or implementation of the Carbon language - who need a detailed understanding of the intended design. -- People writing Carbon code who wish to understand why the language rules are - the way they are. - -For Carbon developers, documentation that is more suitable for learning the -language will be made available separately. +rationale for that design. ## Context and disclaimer @@ -122,10 +109,8 @@ themselves) is also important. It is both an important signal but also a bias. ### Example code -In order to keep example code consistent, we are making choices that may change -later. In particular, where `$` is shown in examples, it is a placeholder: `$` -is a well-known bad symbol due to international keyboard layouts, and will be -cleaned up during evolution. +Some syntax used in example code is provisional or placeholder, and may change +later. ## Basic syntax @@ -837,7 +822,7 @@ be used to instantiate the parameterized definition with the provided arguments in order to produce a complete type. For example: ```carbon -class Stack(T:$$ Type) { +class Stack(template T:! Type) { var storage: Array(T); fn Push(value: T); @@ -867,7 +852,7 @@ arguments. The runtime call then passes the remaining arguments to the resulting complete definition. ```carbon -fn Convert[T:$$ Type](source: T, U:$$ Type) -> U { +fn Convert[template T:! Type](source: T, template U:! Type) -> U { var converted: U = source; return converted; } diff --git a/docs/design/templates.md b/docs/design/templates.md index 753a5e5f7107..7377e68ed494 100644 --- a/docs/design/templates.md +++ b/docs/design/templates.md @@ -44,11 +44,11 @@ are subject to full instantiation -- other parameters will be type checked and bound early to the extent possible. For example: ``` -class Stack(Type$$ T) { - var Array(T) storage; +class Stack(template T:! Type) { + var storage: Array(T); - fn Push(T value); - fn Pop() -> T; + fn Push[addr me: Self*](value: T); + fn Pop[addr me: Self*]() -> T; } ``` @@ -59,23 +59,23 @@ instantiation. ### Functions with template parameters -Both implicit and explicit function parameters in Carbon can be marked as +Both deduced and explicit function parameters in Carbon can be marked as template parameters. When called, the arguments to these parameters trigger instantiation of the function definition, fully type checking and resolving that -definition after substituting in the provided (or computed if implicit) +definition after substituting in the provided (or computed if deduced) arguments. The runtime call then passes the remaining arguments to the resulting complete definition. ``` -fn Convert[Type$$ T](T source, Type$$ U) -> U { - var U converted = source; +fn Convert[template T:! Type](source: T, template U:! Type) -> U { + var converted: U = source; return converted; } -fn Foo(Int i) -> Float { - // Instantiates with the `T` implicit argument set to `Int` and the `U` - // explicit argument set to `Float`, then calls with the runtime value `i`. - return Convert(i, Float); +fn Foo(i: i32) -> f32 { + // Instantiates with the `T` deduced argument set to `i32` and the `U` + // explicit argument set to `f32`, then calls with the runtime value `i`. + return Convert(i, f32); } ``` diff --git a/docs/guides/README.md b/docs/guides/README.md index 3187b6fc08c2..95b7dbcec4a2 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -6,5 +6,7 @@ Exceptions. See /LICENSE for license information. SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception --> -This directory contains end user documentation on how to use Carbon. These -should be focused on people trying to use and write code in Carbon. +This directory contains end-user documentation on how to use Carbon, focused on +people trying to use and write code in Carbon. + +- [Glossary](glossary.md) diff --git a/docs/project/README.md b/docs/project/README.md index feabb4550067..4ed6b3aec61a 100644 --- a/docs/project/README.md +++ b/docs/project/README.md @@ -7,4 +7,19 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception --> This directory contains project-related documentation for Carbon. Information -about how the project works, goals and community information belong here. +about how the project works, goals, and community information belong here. + +- [Goals](goals.md), and [principles](principles/README.md) derived from those + goals +- [Roadmap](roadmap.md) and the [process](roadmap_process.md) for updating it +- Carbon's process for [evolution and governance](evolution.md) +- [Criteria for Carbon to go public](going_public.md) +- [Groups](groups.md) used for contacting key contributors and determining + access +- Contributing to Carbon: + - [Tools used when contributing to Carbon](contribution_tools.md) + - Style guides for [language design](design_style_guide.md) and + [C++ code](cpp_style_guide.md) + - How Carbon does [code review](code_review.md) + - [Trunk-based pull-request GitHub workflow](pull_request_workflow.md) + used by Carbon diff --git a/docs/project/principles/README.md b/docs/project/principles/README.md index 5141683955db..f1e1b4e83a71 100644 --- a/docs/project/principles/README.md +++ b/docs/project/principles/README.md @@ -20,3 +20,11 @@ principle can help achieve consistency across those multiple designs. Note that these principles seek to establish both the approaches the project wants to pursue, as well as those we want to exclude. + +- [Errors are values](error_handling.md) +- [Information accumulation](information_accumulation.md) +- [Low context-sensitivity](low_context_sensitivity.md) +- [Prefer providing only one way to do a given thing](one_way.md) +- [Safety strategy](safety_strategy.md) +- [One static open extension mechanism](static_open_extension.md) +- [Success criteria](success_criteria.md)