Fix links in Markdown (#174)

bufbuild · Jul 28, 2022 · 5466cf6 · 5466cf6
1 parent 1448b9e
commit 5466cf6
Show file tree

Hide file tree

Showing 7 changed files with 69 additions and 59 deletions.
diff --git a/README.md b/README.md
@@ -64,19 +64,13 @@ The implementation is covered by the protocol buffers
 
 ### Packages
 
-#### @bufbuild/protoc-gen-es
-This package provides the code generator plugin `protoc-gen-es`. The code it
-generates depends on `@bufbuild/protobuf`.  
-[Source](packages/protoc-gen-es) | [npmjs.com](https://www.npmjs.com/package/@bufbuild/protoc-gen-es)
-
-#### @bufbuild/protobuf
-This package provides the runtime library for the code generator plugin
-[`protoc-gen-es`](https://github.com/bufbuild/packages/protoc-gen-es).  
-[Source](packages/protobuf) | [npmjs.com](https://www.npmjs.com/package/@bufbuild/protobuf)
-
-#### @bufbuild/protoplugin
-This package helps to create your own code generator plugin.  
-[Source](packages/protoplugin) | [npmjs.com](https://www.npmjs.com/package/@bufbuild/protoplugin)
+- [@bufbuild/protoc-gen-es](https://www.npmjs.com/package/@bufbuild/protoc-gen-es):
+  Provides the code generator plugin `protoc-gen-es` ([source](packages/protoc-gen-es)).   
+  The code it generates depends on `@bufbuild/protobuf`.
+- [@bufbuild/protobuf](https://www.npmjs.com/package/@bufbuild/protobuf):
+  The runtime library for the code generator plugin `protoc-gen-es` ([source](packages/protobuf)).
+- [@bufbuild/protoplugin](https://www.npmjs.com/package/@bufbuild/protoplugin):
+  Helps to create your own code generator plugin ([source](packages/protoplugin)).
 
 
 ### Copyright

diff --git a/docs/generated_code.md b/docs/generated_code.md
@@ -28,7 +28,8 @@ We recommend [`buf`](https://github.com/bufbuild/buf) as a protocol buffer compi
 [`protoc`](https://github.com/protocolbuffers/protobuf/releases) works as well.
 
 If you have the compiler set up, you can install the code generator plugin, as well as the
-accompanying runtime package [`@bufbuild/protobuf`](../packages/protobuf) with:
+accompanying runtime package [@bufbuild/protobuf][pkg-protobuf] 
+with:
 
 ```shell
 npm install @bufbuild/protoc-gen-es @bufbuild/protobuf
@@ -63,7 +64,7 @@ protoc -I . --plugin ./node_modules/.bin/protoc-gen-es --es_out src/gen --es_opt
 ```
 
 To learn about other ways to install the plugin, and about the available plugin options, 
-see [`@bufbuild/protoc-gen-es`](../packages/protoc-gen-es).
+see [@bufbuild/protoc-gen-es](https://www.npmjs.com/package/@bufbuild/protoc-gen-es).
 
 
 
@@ -94,8 +95,9 @@ For the following message declaration:
 message Example {}
 ```
 
-we generate a class called `Example`, which extends the base class [Message](https://github.com/bufbuild/protobuf-es/blob/tstamm/add-docs/packages/protobuf/src/message.ts#L40)
-provided by [@bufbuild/protobuf](../packages/protobuf). See the [runtime API documentation](#runtime-api) for details.
+we generate a class called `Example`, which extends the base class [Message][src-message]
+provided by [@bufbuild/protobuf][pkg-protobuf]. 
+See the [runtime API documentation](#runtime-api) for details.
 
 Note that some names cannot be used as class names and will be escaped by adding the suffix `$`.
 For example, a protobuf message `break` will become a class `break$`.
@@ -162,8 +164,7 @@ all values typed as `bigint` will actually be strings.
 
 For presentation purposes, it is always safe to simply call `toString()` on
 the field value. For more detailed information, see the conversion utility
-[`protoInt64`](https://github.com/bufbuild/protobuf-es/blob/5609f7aab3dcfbb468871774c70d2343ac0f265e/packages/protobuf/src/proto-int64.ts#L65)
-provided by [@bufbuild/protobuf](../packages/protobuf).
+[`protoInt64`][src-proto-int64] provided by [@bufbuild/protobuf][pkg-protobuf].
 
 
 ### Message fields
@@ -392,3 +393,7 @@ deprecatedField = "";
 If you mark a file as deprecated, we generate `@deprecated` JSDoc tags for all
 symbols in this file.
 
+
+[src-proto-int64]: https://github.com/bufbuild/protobuf-es/blob/5609f7aab3dcfbb468871774c70d2343ac0f265e/packages/protobuf/src/proto-int64.ts#L65
+[src-message]: https://github.com/bufbuild/protobuf-es/blob/9b8efb4f4eb8ff8ce9f56798e769914ee2069cd1/packages/protobuf/src/message.ts#L40
+[pkg-protobuf]: https://www.npmjs.com/package/@bufbuild/protobuf
diff --git a/docs/migrating.md b/docs/migrating.md
@@ -307,7 +307,7 @@ change your compiler invocation as follows:
 ### Well-known types
 
 With `protobuf-ts` you are always using locally generated versions of well-known types. 
-With Protobuf-ES, you import them from `@bufbuild/protobuf`:
+With Protobuf-ES, you import them from [@bufbuild/protobuf](https://www.npmjs.com/package/@bufbuild/protobuf):
 
 ```diff
 - import { Timestamp } from "./google/protobuf/timestamp_pb";

diff --git a/docs/releasing.md b/docs/releasing.md
@@ -3,8 +3,8 @@ Release
 
 ## Cutting a release
 
-This guide is a step-by-step process for cutting a release for `@bufbuild/protobuf` 
-and `@bufbuild/protoc-gen-es`.
+This guide is a step-by-step process for cutting a release for [@bufbuild/protobuf](https://www.npmjs.com/package/@bufbuild/protobuf) 
+and [@bufbuild/protoc-gen-es](https://www.npmjs.com/package/@bufbuild/protoc-gen-es).
 
 
 ### Prerequisites

diff --git a/docs/runtime_api.md b/docs/runtime_api.md
@@ -2,7 +2,7 @@ Protobuf-ES: Runtime API
 ========================
 
 The runtime library for the generated code is provided by the npm package 
-[@bufbuild/protobuf](../packages/protobuf). This is a detailed overview of the features 
+[@bufbuild/protobuf][pkg-protobuf]. This is a detailed overview of the features 
 provided by the library.
 
 - [Message class](#message-class)
@@ -25,7 +25,7 @@ provided by the library.
 
 ## Message class
 
-All generated messages extends the base class [Message](../packages/protobuf/src/message.ts#L40).
+All generated messages extends the base class [Message][src-message].
 It provides a few helpful methods to compare, clone, and serialize, and a convenient constructor. 
 All message classes also come with some static properties with metadata, and static convenience methods.
 
@@ -81,16 +81,16 @@ foo = "";
 
 Protobuf fields map to default values as follows:
 
-| Protobuf field     | Class property default value                                      |
-|--------------------|-------------------------------------------------------------------|
-| bool               | `false`                                                           |
-| string             | `""`                                                              |
-| other scalar types | see [intrinsic default values](./generated_code.md#scalar-fields) |
-| optional scalar    | `undefined`                                                       |
-| message            | `undefined`                                                       |
-| map                | `{}`                                                              |
-| repeated           | `[]`                                                              |
-| oneof              | `{ case: undefined }`                                             |
+| Protobuf field     | Class property default value                                         |
+|--------------------|----------------------------------------------------------------------|
+| bool               | `false`                                                              |
+| string             | `""`                                                                 |
+| other scalar types | see [scalar field default values](./generated_code.md#scalar-fields) |
+| optional scalar    | `undefined`                                                          |
+| message            | `undefined`                                                          |
+| map                | `{}`                                                                 |
+| repeated           | `[]`                                                                 |
+| oneof              | `{ case: undefined }`                                                |
 
 
 ### Accessing fields
@@ -230,10 +230,9 @@ const json = example.toJson();
 Example.fromJson(json);
 ```
 
-But the result will be a [JSON value](../packages/protobuf/src/json-format.ts#L139-L154) –
-a primitive JavaScript that can be converted to a JSON string with the built-in function
-`JSON.stringify()`. For convenience, we also provide methods that include the stringify
-step:
+But the result will be a [JSON value][src-json-value] – a primitive JavaScript that can 
+be converted to a JSON string with the built-in function `JSON.stringify()`. For 
+convenience, we also provide methods that include the stringify step:
 
 
 ```typescript
@@ -267,20 +266,18 @@ For enumerations, we lean on TypeScript enums. A quick refresher about them:
 - TypeScript enums are just plain objects in JavaScript.
 - TypeScript enums support aliases - as does protobuf with the `allow_alias` option.
 
-However, similar to MessageType, there is also [`EnumType`](../packages/protobuf/src/enum.ts#L15).
-It provides the fully qualified protobuf type name, as well as the original values and their
-names. Use  [`proto3.getEnumType()`](../packages/protobuf/src/private/proto-runtime.ts#L81-L86)
-to retrieve the EnumType for a given enum.
+However, similar to MessageType, there is also [`EnumType`][src-enum-type].
+It provides the fully qualified protobuf type name, as well as the original values and 
+their names. Use  [`proto3.getEnumType()`][src-proto3-getEnumType] to retrieve the 
+EnumType for a given enum.
 
-Similar to messages, enums can also be created at run time, via
-[`proto3.makeEnum()`](../packages/protobuf/src/private/proto-runtime.ts#L58).
+Similar to messages, enums can also be created at run time, via [`proto3.makeEnum()`][src-proto3-makeEnum].
 
 
 ## Well-known types
 
-Protocol buffers have a small standard library of well-known types.
-[@bufbuild/protobuf](../packages/protobuf) provides all of them as pre-compiled
-exports.
+Protocol buffers have a small standard library of well-known types. 
+[@bufbuild/protobuf][pkg-protobuf] provides all of them as pre-compiled exports.
 
 <details><summary>Expand the list of Well-known types</summary>
 
@@ -427,7 +424,7 @@ representation that is suitable to display in a GUI, as a map key, or for simila
 purposes.
 
 In case you simply want to set a field value, for example from an HTML form input,
-use the provided conversion utility [`protoInt64`](https://github.com/bufbuild/protobuf-es/blob/5609f7aab3dcfbb468871774c70d2343ac0f265e/packages/protobuf/src/proto-int64.ts#L65):
+use the provided conversion utility [`protoInt64`][src-proto-int64]:
 
 ```typescript
 import {protoInt64} from "@bufbuild/protobuf";
@@ -447,7 +444,7 @@ third party library like [Long.js](https://www.npmjs.com/package/long).
 
 In the previous section we went through the methods every message class provides,
 including static methods. But we actually generate a few more static properties
-with metadata. The static shape of the generated class is a [`MessageType`](../packages/protobuf/src/message-type.ts#L27),
+with metadata. The static shape of the generated class is a [`MessageType`][src-message-type],
 a representation of the _type_ of a message.
 
 Such a type can actually be created at run time. We can take a peek at the [generated
@@ -503,12 +500,12 @@ Protobuf compilers such as [`buf`](https://github.com/bufbuild/buf) or `protoc`
 buf generate --output image.bin
 ```
 
-Using a [`DescriptorRegistry`](../packages/protobuf/src/legacy-descriptor-registry.ts#L88), you
+Using [`createRegistryFromDescriptors()`][src-create-registry-from-desc], you
 can create types at run time from a set of descriptors created by a protocol buffers
 compiler:
 
 ```typescript
-const registry = new DescriptorRegistry.fromFileDescriptorSet(
+const registry = createRegistryFromDescriptors(
   readFileSync("image.bin")
 );
 const Example = registry.findMessage("doc.Example");
@@ -533,25 +530,26 @@ walkFields(message);
 ```
 
 Note that the example does not handle oneof groups. Please consult the sources code 
-for examples how to include them. The JSON and binary serialization mechanisms use this technique. 
+for examples how to include them. The JSON and binary serialization mechanisms use this 
+technique. 
 
 
 ## Advanced TypeScript types
 
 ### PartialMessage
 
 The object initializers accepted by message constructors are defined by the type 
-[`PartialMessage<T>`](../packages/protobuf/src/message.ts#L145-L153).
-It is similar to the TypeScript built-in type `Partial`, but works recursively. 
+[`PartialMessage<T>`][src-partial-message]. It is similar to the TypeScript built-in type 
+`Partial`, but works recursively. 
 
 This type is well suited in case you know the type of a message, but want to allow 
 an instance to be given in the most flexible way.
 
 
 ### PlainMessage
 
-[`PlainMessage<T>`](../packages/protobuf/src/message.ts#L136-L140) represents _just_
-the fields of a message, without their methods. 
+[`PlainMessage<T>`][src-plain-message] represents _just_ the fields of a message, without 
+their methods. 
 
 In contrast to `PartialMessage`, `PlainMessage` requires all properties to be
 provided. And since it is not recursive, message fields must provide the exact type.
@@ -574,11 +572,24 @@ let plain: PlainMessage<Example> = {...example};
 
 ### AnyMessage
 
-If you want to handle messages of unknown type, the type [`AnyMessage`](https://github.com/bufbuild/protobuf-es/blob/584eddddc8ed53fd0df763355e450e3419259258/packages/protobuf/src/message.ts#L24-L31) 
+If you want to handle messages of unknown type, the type [`AnyMessage`][src-any-message] 
 provides a convenient index signature to access fields:
 
 ```typescript
 const anyMessage: AnyMessage = example;
 example["foo"];
 ```
 
+
+[src-proto-int64]: https://github.com/bufbuild/protobuf-es/blob/5609f7aab3dcfbb468871774c70d2343ac0f265e/packages/protobuf/src/proto-int64.ts#L65
+[src-message]: https://github.com/bufbuild/protobuf-es/blob/9b8efb4f4eb8ff8ce9f56798e769914ee2069cd1/packages/protobuf/src/message.ts#L40
+[src-message-type]: https://github.com/bufbuild/protobuf-es/blob/9b8efb4f4eb8ff8ce9f56798e769914ee2069cd1/packages/protobuf/src/message-type.ts#L27
+[src-enum-type]: https://github.com/bufbuild/protobuf-es/blob/9b8efb4f4eb8ff8ce9f56798e769914ee2069cd1/packages/protobuf/src/enum.ts#L15
+[src-json-value]: https://github.com/bufbuild/protobuf-es/blob/9b8efb4f4eb8ff8ce9f56798e769914ee2069cd1/packages/protobuf/src/json-format.ts#L139-L154
+[src-proto3-getEnumType]: https://github.com/bufbuild/protobuf-es/blob/9b8efb4f4eb8ff8ce9f56798e769914ee2069cd1/packages/protobuf/src/private/proto-runtime.ts#L81-L86
+[src-proto3-makeEnum]: https://github.com/bufbuild/protobuf-es/blob/9b8efb4f4eb8ff8ce9f56798e769914ee2069cd1/packages/protobuf/src/private/proto-runtime.ts#L58
+[src-create-registry-from-desc]: https://github.com/bufbuild/protobuf-es/blob/9b8efb4f4eb8ff8ce9f56798e769914ee2069cd1/packages/protobuf/src/create-registry-from-desc.ts#L81
+[src-partial-message]: https://github.com/bufbuild/protobuf-es/blob/9b8efb4f4eb8ff8ce9f56798e769914ee2069cd1/packages/protobuf/src/message.ts#L143
+[src-plain-message]: https://github.com/bufbuild/protobuf-es/blob/9b8efb4f4eb8ff8ce9f56798e769914ee2069cd1/packages/protobuf/src/message.ts#L137
+[src-any-message]: https://github.com/bufbuild/protobuf-es/blob/9b8efb4f4eb8ff8ce9f56798e769914ee2069cd1/packages/protobuf/src/message.ts#L25
+[pkg-protobuf]: https://www.npmjs.com/package/@bufbuild/protobuf
diff --git a/packages/protobuf/README.md b/packages/protobuf/README.md
@@ -1,7 +1,7 @@
 # @bufbuild/protobuf
 
 This package provides the runtime library for the code generator plugin
-[`protoc-gen-es`](https://github.com/bufbuild/packages/protoc-gen-es).
+[protoc-gen-es](https://www.npmjs.com/package/@bufbuild/protoc-gen-es).
 
 ## Protocol Buffers for ECMAScript
 

diff --git a/packages/protoc-gen-es/README.md b/packages/protoc-gen-es/README.md
@@ -1,7 +1,7 @@
 # @bufbuild/protoc-gen-es
 
 This package provides the code generator plugin `protoc-gen-es`. The code it 
-generates depends on `@bufbuild/protobuf`.
+generates depends on [@bufbuild/protobuf](https://www.npmjs.com/package/@bufbuild/protobuf).
 
 ## Protocol Buffers for ECMAScript