From 6e6a675c67a95a3af9634e24eea4c607105ffddf Mon Sep 17 00:00:00 2001
From: Rich Harris <richard.a.harris@gmail.com>
Date: Mon, 24 Jun 2019 16:49:26 -0400
Subject: [PATCH] tweak docs a bit

---
 site/content/docs/01-component-format.md | 73 +++++++++++++++---------
 site/content/docs/02-template-syntax.md  | 12 +++-
 2 files changed, 57 insertions(+), 28 deletions(-)

diff --git a/site/content/docs/01-component-format.md b/site/content/docs/01-component-format.md
index ddd2667075..b60457d5af 100644
--- a/site/content/docs/01-component-format.md
+++ b/site/content/docs/01-component-format.md
@@ -28,41 +28,60 @@ A `<script>` block contains JavaScript that runs when a component instance is cr
 
 ---
 
-Svelte uses the `export` keyword to mark a variable declaration as a *property* or *prop*, which means it becomes accessible to consumers of the component:
+Svelte uses the `export` keyword to mark a variable declaration as a *property* or *prop*, which means it becomes accessible to consumers of the component (see the section on [attributes and props](docs#Attributes_and_props) for more information).
 
 ```html
 <script>
-	// these properties can be set externally
 	export let foo;
+
+	// Values that are passed in as props
+	// are immediately available
+	console.log({ foo });
+</script>
+```
+
+---
+
+You can specify a default value, which will be used if the component's consumer doesn't specify a prop.
+
+In development mode (see the [compiler options](docs#svelte_compile)), a warning will be printed if no default is provided and the consumer does not specify a value. To squelch this warning, ensure that a default is specified, even if it is `undefined`.
+
+```html
+<script>
 	export let bar = 'optional default value';
+	export let baz = undefined;
+</script>
+```
+
+---
 
-	// you can use export { ... as ... } to have
-	// props whose names are reserved keywords
-	let clazz;
-	export { clazz as class };
+If you export a `const`, `class` or `function`, it is readonly from outside the component. Function *expressions* are valid props, however.
 
-	// this property is readonly externally
-	export const buzz = 'buzz';
+```html
+<script>
+	// these are readonly
+	export const thisIs = 'readonly';
 
-	// Values that are passed in as props
-	// are immediately available
-	console.log(foo, bar);
-	
-	// Function expressions can also be props
-	export let format = (number) => (number.toFixed(2));
-
-	// Function declarations are added as methods
-	// on the component, rather than props
-	export function greetMethod() {
-		alert(`I'm a <${this.constructor.name}>!`);
+	export function greet(name) {
+		alert(`hello ${name}!`);
 	}
 
-	// you can also use export { ... as ... } to have
-	// methods whose names are reserved keywords
-	function del() {
-		do_something();
-	}
-	export { del as delete };
+	// this is a prop
+	export let format = n => n.toFixed(2);
+</script>
+```
+
+---
+
+You can use reserved words as prop names.
+
+```html
+<script>
+	let className;
+
+	// creates a `class` property, even
+	// though it is a reserved word
+	export { className as class };
 </script>
 ```
 
@@ -81,8 +100,8 @@ Because Svelte's reactivity is based on assignments, using array methods like `.
 	let count = 0;
 
 	function handleClick () {
-		// calling this function will trigger a re-render
-		// if the markup references `count`
+		// calling this function will trigger an
+		// update if the markup references `count`
 		count = count + 1;
 	}
 </script>
diff --git a/site/content/docs/02-template-syntax.md b/site/content/docs/02-template-syntax.md
index ceaa19a398..981224fc14 100644
--- a/site/content/docs/02-template-syntax.md
+++ b/site/content/docs/02-template-syntax.md
@@ -20,7 +20,7 @@ A lowercase tag, like `<div>`, denotes a regular HTML element. A capitalised tag
 ```
 
 
-### Attributes
+### Attributes and props
 
 ---
 
@@ -76,6 +76,16 @@ When the attribute name and value match (`name={name}`), they can be replaced wi
 
 ---
 
+By convention, values passed to components are referred to as *properties* or *props* rather than *attributes*, which are a feature of the DOM.
+
+As with elements, `name={name}` can be replaced with the `{name}` shorthand.
+
+```html
+<Widget foo={bar} answer={42} text="hello"/>
+```
+
+---
+
 *Spread attributes* allow many attributes or properties to be passed to an element or component at once.
 
 An element or component can have multiple spread attributes, interspersed with regular ones.