Added a new top level entry point: hooks.dart

improve dartdocs and IDE usability when writing hooks

Author: robbecker-wf

CHANGELOG.md

@@ -1,5 +1,6 @@
 ## 6.2.1
  - Consolidated utils from src/util.dart into src/common/utils/utils.dart
+ - Added a new top level entry point `hooks.dart` to improve dartdocs and IDE usability when writing hooks
 
 ## 6.2.0
  - Added Checks API https://github.com/SpinlockLabs/github.dart/pull/182

lib/hooks.dart

@@ -0,0 +1,11 @@
+/// This entrypoint is here so that dartdoc will generate documentation for
+/// files under lib/src/server. This is only necessary because conditional 
+/// import/export isn't well supported in the Dart ecosystem.
+/// 
+/// Add this import if you are in a non-web environment and writing something
+/// that uses github hooks. For more information, see github hooks documentation 
+/// https://developer.github.com/v3/repos/hooks/
+/// `import 'pacakge:github/hooks.dart';`
+library hooks;
+
+export 'src/server/xplat_server.dart';

lib/src/common/xplat_common.dart

@@ -1,8 +1,21 @@
 import 'package:github/src/common.dart';
 
+/// Looks for GitHub Authentication information from the current environment.
+/// 
+/// If in a browser context, it will look through query string parameters first
+/// and then sessionStorage. 
+/// 
+/// If in a server, command line or Flutter context it will use the system environment variables.
+///
+/// In both contexts it delegates to [findAuthenticationInMap] to find the
+/// github token or username and password.
 Authentication findAuthenticationFromEnvironment() =>
     Authentication.anonymous();
 
+/// Checks the passed in map for keys in [COMMON_GITHUB_TOKEN_ENV_KEYS]. 
+/// The first one that exists is used as the github token to call [Authentication.withToken] with.
+/// If the above fails, the GITHUB_USERNAME and GITHUB_PASSWORD keys will be checked.
+/// If those keys both exist, then [Authentication.basic] will be used.
 Authentication findAuthenticationInMap(Map map) {
   for (final key in COMMON_GITHUB_TOKEN_ENV_KEYS) {
     if (map.containsKey(key)) {