2 files changed, 94 insertions(+), 0 deletions(-)

M artistcredit.go
M models.go

@@ 2,6 2,13 @@ package musicbrainzws2
 
 import "strings"
 
+// Artist credits indicate who is the main credited artist (or artists) for
+// releases, release groups, tracks and recordings, and how they are credited.
+//
+// They consist of artists, with (optionally) their names as credited in the
+// specific release, track, etc., and join phrases between them.
+//
+// See https://musicbrainz.org/doc/Artist_Credits
 type ArtistCredit []ArtistCreditEntry
 
 type ArtistCreditEntry struct {

@@ 177,6 177,9 @@ type ErrorResult struct {
 
 // Core entity types
 
+// Areas are geographic regions or settlements.
+//
+// See https://musicbrainz.org/doc/Area
 type Area struct {
 	ID             MBID           `json:"id"`
 	Score          int            `json:"score"`


@@ 199,6 202,14 @@ type Area struct {
 	ISO31662Codes  []ISO31662Code `json:"iso-3166-2-codes"`
 }
 
+// An artist is generally a musician (or musician persona), group of musicians,
+// or other music professional (like a producer or engineer).
+//
+// Occasionally, it can also be a non-musical person (like a photographer, an
+// illustrator, or a poet whose writings are set to music), or even a fictional
+// character.
+//
+// See https://musicbrainz.org/doc/Artist
 type Artist struct {
 	ID             MBID           `json:"id"`
 	Score          int            `json:"score"`


@@ 231,6 242,12 @@ type Artist struct {
 	Works          []Work         `json:"works"`
 }
 
+// An event refers to an organised activity that people can attend, and is
+// relevant to the performance, production or celebration of music.
+//
+// In most cases, this means live concerts, festivals and other similar activities.
+//
+// See https://musicbrainz.org/doc/Event
 type Event struct {
 	ID             MBID         `json:"id"`
 	Score          int          `json:"score"`


@@ 259,12 276,20 @@ type Event struct {
 // gets automatically applied to the entity.
 //
 // Like tags genres can also be submitted with [Client.SubmitTags].
+//
+// See https://musicbrainz.org/doc/Genre
 type Genre struct {
 	ID             MBID   `json:"id"`
 	Disambiguation string `json:"disambiguation"`
 	Tag
 }
 
+// Instruments are devices created or adapted to make musical sounds.
+//
+// Instruments are primarily used in relationships between two other entities,
+// e.g. to specify the instrument played by an artist on a recording.
+//
+// See https://musicbrainz.org/doc/Instrument
 type Instrument struct {
 	ID             MBID         `json:"id"`
 	Score          int          `json:"score"`


@@ 284,6 309,11 @@ type Instrument struct {
 	UserGenres     []Genre      `json:"user-genres"`
 }
 
+// Labels in MusicBrainz refer mainly to imprints.
+//
+// In some cases a label entity may represent a record company or music holding company.
+//
+// See https://musicbrainz.org/doc/Label
 type Label struct {
 	ID             MBID         `json:"id"`
 	Score          int          `json:"score"`


@@ 310,6 340,9 @@ type Label struct {
 	Releases       []Release    `json:"releases"`
 }
 
+// A place is a building or outdoor area used for performing or producing music.
+//
+// See https://musicbrainz.org/doc/Place
 type Place struct {
 	ID             MBID           `json:"id"`
 	Score          int            `json:"score"`


@@ 332,6 365,9 @@ type Place struct {
 	Area           *Area          `json:"area,omitempty"`
 }
 
+// A recording represents distinct audio that has been used to produce at least one released track.
+//
+// See https://musicbrainz.org/doc/Recording
 type Recording struct {
 	ID               MBID         `json:"id"`
 	Score            int          `json:"score"`


@@ 353,6 389,10 @@ type Recording struct {
 	Releases         []Release    `json:"releases"`
 }
 
+// A MusicBrainz release represents the unique release (i.e. issuing) of a
+// product containing at least one audio [Medium].
+//
+// See https://musicbrainz.org/doc/Release
 type Release struct {
 	ID                 MBID                `json:"id"`
 	Score              int                 `json:"score"`


@@ 385,6 425,11 @@ type Release struct {
 	UserGenres         []Genre             `json:"user-genres"`
 }
 
+// A release group, as the name suggests, is used to group releases into a single logical entity.
+//
+// Every [Release] belongs to one, and only one, release group.
+//
+// See https://musicbrainz.org/doc/Release_Group
 type ReleaseGroup struct {
 	ID               MBID         `json:"id"`
 	Score            int          `json:"score"`


@@ 408,6 453,10 @@ type ReleaseGroup struct {
 	Releases         []Release    `json:"releases"`
 }
 
+// A series is a sequence of separate release groups, releases, recordings,
+// works, artists or events with a common theme.
+//
+// See https://musicbrainz.org/doc/Series
 type Series struct {
 	ID             MBID         `json:"id"`
 	Score          int          `json:"score"`


@@ 426,6 475,14 @@ type Series struct {
 	UserGenres     []Genre      `json:"user-genres"`
 }
 
+// In MusicBrainz terminology, a work is a distinct intellectual or artistic
+// creation, which can be expressed in the form of one or more audio recordings.
+//
+// While a work in MusicBrainz is usually musical in nature, it is not
+// necessarily so. For example, a work could be a novel, play, poem or essay,
+// later recorded as an oratory or audiobook.
+//
+// See https://musicbrainz.org/doc/Work
 type Work struct {
 	ID             MBID            `json:"id"`
 	Score          int             `json:"score"`


@@ 447,6 504,9 @@ type Work struct {
 	UserGenres     []Genre         `json:"user-genres"`
 }
 
+// A URL in MusicBrainz is a specific entity representing a regular internet Uniform Resource Locator.
+//
+// See https://musicbrainz.org/doc/URL
 type URL struct {
 	ID           MBID               `json:"id"`
 	Score        int                `json:"score"`


@@ 467,6 527,10 @@ type Annotation struct {
 	Text   string `json:"text"`
 }
 
+// Collections are lists of entities that users can create, title and edit as they see fit.
+// Each collection can be private or public.
+//
+// See https://musicbrainz.org/doc/Collections
 type Collection struct {
 	ID         MBID   `json:"id"`
 	Name       string `json:"name"`


@@ 550,6 614,9 @@ type WorkCollection struct {
 
 // Other entities
 
+// Aliases are alternative names for all types of MusicBrainz entities.
+//
+// See https://musicbrainz.org/doc/Aliases
 type Alias struct {
 	Type      string      `json:"type"`
 	TypeID    MBID        `json:"type-id"`


@@ 561,6 628,7 @@ type Alias struct {
 	IsPrimary bool        `json:"primary"`
 }
 
+// Holds information about the artwork available for a release on the Cover Art Archive.
 type CoverArtArchiveInfo struct {
 	HasArtwork bool `json:"artwork"`
 	Count      int  `json:"count"`


@@ 607,6 675,16 @@ type LifeSpan struct {
 	HasEnded bool        `json:"ended"`
 }
 
+// In MusicBrainz terminology, a prototypical medium is one of the physical,
+// separate things you would get when you buy something in a record store.
+//
+// They are the individual CDs, vinyls, etc. contained within the packaging of
+// a [Release]. Mediums are always included in a release, and have a position in
+// said release (e.g. disc 1 or disc 2). They have a format, like CD, 12" vinyl
+// or cassette (in some cases this will be unknown), and can have an optional
+// title (e.g. disc 2: The Early Years).
+//
+// See https://musicbrainz.org/doc/Medium
 type Medium struct {
 	Title       string   `json:"title"`
 	Format      string   `json:"format"`


@@ 685,6 763,15 @@ func (t Tag) String() string {
 	return t.Name
 }
 
+// In MusicBrainz, a track is the way a [Recording] is represented on a
+// particular [Release] (or, more exactly, on a particular [Medium]).
+//
+// Every track has a title (see the guidelines for titles) and is credited to
+// one or more artists. Tracks are additionally assigned MBIDs, though they
+// cannot be the target of Relationships or other properties conventionally
+// available to entities.
+//
+// See https://musicbrainz.org/doc/Track
 type Track struct {
 	ID           MBID         `json:"id"`
 	Title        string       `json:"title"`