Add documentation to many public members and populate the example dir (GoogleCloudPlatform#226)

Should increase the score of the package

Prepare to release v0.4.1

Author: kevmoo

functions_framework/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## 0.4.1-dev
+## 0.4.1
 
 - Improve package documentation.
 

functions_framework/README.md

@@ -86,7 +86,7 @@ properly format your code.
 
 ## Licensing
 
-Apache 2.0; see [`LICENSE`](LICENSE) for details.
+Apache 2.0; see [`LICENSE`][license] for details.
 
 <!-- Repo links -->
 [ff_dart]: https://github.com/GoogleCloudPlatform/functions-framework-dart
@@ -123,3 +123,4 @@ https://github.com/GoogleCloudPlatform/functions-framework-dart/actions?query=wo
 [cloud run quickstart]: https://github.com/GoogleCloudPlatform/functions-framework-dart/blob/main/docs/quickstarts/03-quickstart-cloudrun.md
 [quickstarts]: https://github.com/GoogleCloudPlatform/functions-framework-dart/tree/main/docs/quickstarts
 [contributing]: https://github.com/GoogleCloudPlatform/functions-framework-dart/blob/main/CONTRIBUTING.md
+[license]: https://github.com/GoogleCloudPlatform/functions-framework-dart/blob/main/functions_framework/LICENSE

functions_framework/example/readme.md

@@ -0,0 +1,4 @@
+# Functions Framework Examples
+
+For usage examples, see
+https://github.com/GoogleCloudPlatform/functions-framework-dart/tree/main/examples

functions_framework/lib/functions_framework.dart

@@ -12,6 +12,18 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+/// Provides the features needed to *define* Cloud Functions.
+///
+/// ```dart
+/// // lib/functions.dart
+/// import 'package:functions_framework/functions_framework.dart';
+/// import 'package:shelf/shelf.dart';
+///
+/// @CloudFunction()
+/// Response function(Request request) => Response.ok('Hello, World!');
+/// ```
+library functions_framework;
+
 export 'src/bad_request_exception.dart' show BadRequestException;
 export 'src/cloud_event.dart' show CloudEvent;
 export 'src/cloud_function.dart' show CloudFunction;

functions_framework/lib/serve.dart

@@ -12,6 +12,16 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+/// Provides the features needed to *execute* Cloud Functions.
+///
+/// Typically, this library is imported in `bin/server.dart` or similar.
+///
+/// While it's possible to use this library from hand-written code, you should
+/// use
+/// [package:functions_framework_builder](https://pub.dev/packages/functions_framework_builder)
+/// to generate server code instead.
+library serve;
+
 import 'dart:async';
 import 'dart:io';
 

functions_framework/lib/src/cloud_event.dart

@@ -16,6 +16,10 @@ import 'package:json_annotation/json_annotation.dart';
 
 part 'cloud_event.g.dart';
 
+/// Represents [CloudEvents](https://cloudevents.io/) data.
+///
+/// Use this as the parameter in a function you wish to use as a handler for
+/// CloudEvents.
 @JsonSerializable(includeIfNull: false, checked: true)
 class CloudEvent {
   @JsonKey(required: true)

functions_framework/lib/src/log_severity.dart

@@ -12,6 +12,17 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+import 'request_context.dart';
+import 'typedefs.dart';
+
+/// Allows logging at a specified severity.
+///
+/// Can be used as the second parameter in functions shaped like
+/// [HandlerWithLogger]. Also exposed by [RequestContext].
+///
+/// Compatible with the
+/// [log severities](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity)
+/// support by Google Cloud.
 abstract class RequestLogger {
   const RequestLogger();
 

functions_framework/lib/src/request_context.dart

@@ -15,9 +15,15 @@
 import 'package:meta/meta.dart';
 import 'package:shelf/shelf.dart';
 
+import 'cloud_event.dart';
 import 'log_severity.dart';
 import 'logging.dart';
 
+/// Provides access to a [RequestLogger], the source [Request] and response
+/// headers for a typed function handler.
+///
+/// Can be used as an optional second parameter in a function definition that
+/// accepts a [CloudEvent] or a custom type.
 class RequestContext {
   final RequestLogger logger;
 

functions_framework/lib/src/typedefs.dart

@@ -20,22 +20,43 @@ import 'cloud_event.dart';
 import 'log_severity.dart';
 import 'request_context.dart';
 
+/// The shape of a handler for [CloudEvent] types.
 typedef CloudEventHandler = FutureOr<void> Function(CloudEvent request);
 
+/// The shape of a handler for [CloudEvent] types while also providing a
+/// [RequestContext].
 typedef CloudEventWithContextHandler = FutureOr<void> Function(
   CloudEvent request,
   RequestContext context,
 );
 
+/// The shape of a handler that supports a custom [RequestType] and
+/// [ResponseType].
+///
+/// The [RequestType] must be either a type compatible with a JSON literal or
+/// have a `fromJson` constructor with a single, positional parameter that is
+/// compatible with a JSON literal.
+///
+/// The [ResponseType] must be either a type compatible with a JSON literal or
+/// have a `toJson()` function with a returns type compatible with a JSON
+/// literal.
 typedef JsonHandler<RequestType, ResponseType> = FutureOr<ResponseType>
     Function(RequestType request);
 
+/// The shape of a handler that supports a custom [RequestType] and
+/// [ResponseType] and while also providing a [RequestContext].
+///
+/// See [JsonHandler] for the type requirements for [RequestType] and
+/// [ResponseType].
 typedef JsonWithContextHandler<RequestType, ResponseType>
     = FutureOr<ResponseType> Function(
   RequestType request,
   RequestContext context,
 );
 
+/// The shape of a basic handler that follows the
+/// [package:shelf](https://pub.dev/packages/shelf) [Handler] pattern while also
+/// providing a [RequestLogger].
 typedef HandlerWithLogger = FutureOr<Response> Function(
   Request request,
   RequestLogger logger,

functions_framework/pubspec.yaml

@@ -1,5 +1,5 @@
 name: functions_framework
-version: 0.4.1-dev
+version: 0.4.1
 description: >-
   FaaS (Function as a service) framework for writing portable Dart functions
 repository: https://github.com/GoogleCloudPlatform/functions-framework-dart