From 9637d0e08e7b68bc110a686efd9f6456663656f7 Mon Sep 17 00:00:00 2001
From: Austin Macdonald <austin@dartmouth.edu>
Date: Fri, 26 Apr 2024 15:29:19 -0500
Subject: [PATCH] clarify resource identifier docs

Fixes: #https://github.com/dandi/dandi-cli/issues/1435
---
 dandi/cli/cmd_download.py | 2 ++
 dandi/cli/cmd_ls.py       | 2 ++
 dandi/dandiarchive.py     | 9 +++++++++
 3 files changed, 13 insertions(+)

diff --git a/dandi/cli/cmd_download.py b/dandi/cli/cmd_download.py
index ee43459d6..e40f2b82d 100644
--- a/dandi/cli/cmd_download.py
+++ b/dandi/cli/cmd_download.py
@@ -18,6 +18,8 @@
     help=f"""\
 Download files or entire folders from DANDI.
 
+\b
+{_dandi_url_parser.resource_identifier_primer}
 \b
 {_dandi_url_parser.known_patterns}
     """
diff --git a/dandi/cli/cmd_ls.py b/dandi/cli/cmd_ls.py
index eeb3dbecd..9ac9ed42f 100644
--- a/dandi/cli/cmd_ls.py
+++ b/dandi/cli/cmd_ls.py
@@ -26,6 +26,8 @@
 The arguments may be either resource identifiers or paths to local
 files/directories.
 
+\b
+{_dandi_url_parser.resource_identifier_primer}
 \b
 {_dandi_url_parser.known_patterns}
 """
diff --git a/dandi/dandiarchive.py b/dandi/dandiarchive.py
index 53c3506cb..1c1dc5c8b 100644
--- a/dandi/dandiarchive.py
+++ b/dandi/dandiarchive.py
@@ -675,6 +675,15 @@ class _dandi_url_parser:
             "https://<server>/...",
         ),
     ]
+    resource_identifier_primer = """dandi commands and accept URLs and URL-like identifiers called
+<resource ids> in the following formats for identifying Dandisets, assets, and asset
+collections.
+
+Text in [brackets] is optional.  A server field is a base API or GUI URL
+for a DANDI Archive instance.  If an optional ``version`` field is omitted from
+a URL, the given Dandiset's most recent published version will be used if it
+has one, and its draft version will be used otherwise.
+"""
     known_patterns = "Accepted resource identifier patterns:" + "\n - ".join(
         [""] + [display for _, _, display in known_urls]
     )