document identify_package and locate_package (JuliaLang#45287)

base/loading.jl

@@ -302,25 +302,44 @@ function find_package(arg)
  return locate_package(pkg)
 end
 
-## package identity: given a package name and a context, try to return its identity ##
-identify_package(where::Module, name::String) = identify_package(PkgId(where), name)
+"""
+ Base.identify_package(name::String)::Union{PkgId, Nothing}
+ Base.identify_package(where::Union{Module,PkgId}, name::String)::Union{PkgId, Nothing}
+
+Identify the package by its name from the current environment stack, returning
+its `PkgId`, or `nothing` if it cannot be found.
+
+If only the `name` argument is provided, it searches each environment in the
+stack and its named direct dependencies.
+
+There `where` argument provides the context from where to search for the
+package: in this case it first checks if the name matches the context itself,
+otherwise it searches all recursive dependencies (from the resolved manifest of
+each environment) until it locates the context `where`, and from there
+identifies the depdencency with with the corresponding name.
 
-# identify_package computes the PkgId for `name` from the context of `where`
-# or return `nothing` if no mapping exists for it
+```julia-repl
+julia> Base.identify_package("Pkg") # Pkg is a dependency of the default environment
+Pkg [44cfe95a-1eb2-52ea-b672-e2afdf69b78f]
+
+julia> using LinearAlgebra
+
+julia> Base.identify_package(LinearAlgebra, "Pkg") # Pkg is not a dependency of LinearAlgebra
+
+````
+"""
+identify_package(where::Module, name::String) = identify_package(PkgId(where), name)
 function identify_package(where::PkgId, name::String)::Union{Nothing,PkgId}
  where.name === name && return where
  where.uuid === nothing && return identify_package(name) # ignore `where`
  for env in load_path()
- uuid = manifest_deps_get(env, where, name)
- uuid === nothing && continue # not found--keep looking
- uuid.uuid === nothing || return uuid # found in explicit environment--use it
+ pkgid = manifest_deps_get(env, where, name)
+ pkgid === nothing && continue # not found--keep looking
+ pkgid.uuid === nothing || return pkgid # found in explicit environment--use it
  return nothing # found in implicit environment--return "not found"
  end
  return nothing
 end
-
-# identify_package computes the PkgId for `name` from toplevel context
-# by looking through the Project.toml files and directories
 function identify_package(name::String)::Union{Nothing,PkgId}
  for env in load_path()
  uuid = project_deps_get(env, name)
@@ -329,7 +348,20 @@ function identify_package(name::String)::Union{Nothing,PkgId}
  return nothing
 end
 
-## package location: given a package identity, find file to load ##
+"""
+ Base.locate_package(pkg::PkgId)::Union{String, Nothing}
+
+The path to the entry-point file for the package corresponding to the identifier
+`pkg`, or `nothing` if not found. See also [`identify_package`](@ref).
+
+```julia-repl
+julia> pkg = Base.identify_package("Pkg")
+Pkg [44cfe95a-1eb2-52ea-b672-e2afdf69b78f]
+
+julia> Base.locate_package(pkg)
+"/path/to/julia/stdlib/v$(VERSION.major).$(VERSION.minor)/Pkg/src/Pkg.jl"
+```
+"""
 function locate_package(pkg::PkgId)::Union{Nothing,String}
  if pkg.uuid === nothing
  for env in load_path()

doc/src/base/base.md

@@ -27,8 +27,6 @@ Base.exit
 Base.atexit
 Base.isinteractive
 Base.summarysize
-Base.require
-Base.compilecache
 Base.__precompile__
 Base.include
 Base.MainInclude.include
@@ -435,6 +433,15 @@ Base.functionloc(::Method)
 Base.@locals
 ```
 
+## Code loading
+
+```@docs
+Base.identify_package
+Base.locate_package
+Base.require
+Base.compilecache
+```
+
 ## Internals
 
 ```@docs