From ae27a274c993d7e5f84e79d3e9a6024bc49f0180 Mon Sep 17 00:00:00 2001 From: Philipp Wolfer Date: Sun, 2 Jun 2024 17:08:51 +0200 Subject: [PATCH] Added documentation for the main model structs --- artistcredit.go | 7 ++++ models.go | 87 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 94 insertions(+) diff --git a/artistcredit.go b/artistcredit.go index 147aee8..727aaea 100644 --- a/artistcredit.go +++ b/artistcredit.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 { diff --git a/models.go b/models.go index 18617d0..997e9f1 100644 --- a/models.go +++ b/models.go @@ -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"` -- 2.45.2