document pkg/name

Also, tighten contracts and add `package-source-format?`.

pkgs/racket-pkgs/racket-doc/pkg/scribblings/apis.scrbl

@@ -44,4 +44,5 @@ to the @exec{raco pkg} sub-subcommands.
 
 @include-section["lib.scrbl"]
 @include-section["path.scrbl"]
+@include-section["name.scrbl"]
 @include-section["db.scrbl"]

pkgs/racket-pkgs/racket-doc/pkg/scribblings/name.scrbl

@@ -0,0 +1,44 @@
+#lang scribble/manual
+@(require (for-label racket/base
+                     racket/contract/base
+                     pkg/name))
+                     
+
+@title[#:tag "name"]{Package Source Parsing}
+
+@defmodule[pkg/name]{The @racketmodname[pkg/name] library provides
+functions for parsing and normalizing a package source, especially for
+extracting a package name.}
+
+
+@defproc[(package-source-format? [v any/c]) boolean?]{
+
+Returns @racket[#t] if @racket[v] is @racket['name] , @racket['file],
+@racket['dir], @racket['github], @racket['file-url],
+@racket['dir-url], @racket['link], or @racket['static-link], and
+returns @racket[#f] otherwise.
+
+The @racket['link] and @racket['static-link] formats are the same as
+@racket['dir] in terms of parsing, but they are treated differently
+for tasks such as package installation.}
+
+
+@defproc[(package-source->name [source string?]
+                               [type (or/c package-source-format? #f)
+                                #f])
+          (or/c #f string?)]{
+
+Extracts the @tech{package name} from a @tech{package source}, where
+the package source type is inferred if @racket[type] is @racket[#f].
+If a valid name cannot be inferred, the result is @racket[#f].}
+
+
+@defproc[(package-source->name+type [source string?]
+                                    [type (or/c package-source-format? #f)
+                                     #f])
+          (values (or/c #f string?)
+                  (or/c package-source-format? #f))]{
+
+Like @racket[package-source->name], but also returns the type of the
+source (which is useful when the type is inferred). If the source is
+not well-formed, the second result can be @racket[#f].}

racket/collects/pkg/name.rkt

@@ -6,19 +6,23 @@
          net/url)
 
 (provide
+ package-source-format?
  (contract-out
-  [package-source->name+type (->* (string? (or/c #f symbol?))
+  [package-source->name+type (->* (string? (or/c #f package-source-format?))
                                   (#:complain (-> string? string? any)
                                               #:must-infer-name? boolean?
                                               #:link-dirs? boolean?)
-                                  (values (or/c #f string?) (or/c #f symbol?)))]
+                                  (values (or/c #f string?) (or/c #f package-source-format?)))]
   [package-source->name (->* (string?)
-                             ((or/c #f symbol?))
+                             ((or/c #f package-source-format?))
                              (or/c #f string?))]))
 
 (define rx:package-name #rx"^[-_a-zA-Z0-9]+$")
 (define rx:archive #rx"[.](plt|zip|tar|tgz|tar[.]gz)$")
 
+(define package-source-format?
+  (or/c 'name 'file 'dir 'github 'file-url 'dir-url 'link 'static-link))
+
 (define (validate-name name complain inferred?)
   (and name
        (cond