They even named the main file react.js so when converting/migrating components from React you could (at least some of the time, perhaps) simply leave some of the imports as-is:

import {createHooks, useRef} from './react';

Why does he think they are dangerous?

Austin S. (2020) This Lawyer Ran Errands for His High-Risk Wife. Then an Epidemiologist Rated His Every Move.https://elemental.medium.com/this-lawyer-ran-errands-for-his-high-risk-wife-then-an-epidemiologist-rated-his-every-move-f9a926ad96ec

Examples of projects that use documentation well

(chech the list below)

Documenting code:

• describing use to your users (main audience)

Class method should contain:

• brief description
• arguments
• label on default/optional arguments
• side effects description
• raised exceptions
• restrictions on when the method can be called

(check example below)

Comments should be as concise as possible. Moreover, you should follow 4 rules of Jeff Atwood:

1. Keep comments close to the code being described.
2. Don't use complex formatting (such as tables).
3. Don't comment obvious things.
4. Design code in a way it comments itself.

Type hinting introduced in Python 3.5 extends 4 rules of Jeff Atwood and comments the code itself, such as this example:

def hello_name(name: str) -> str:
    return(f"Hello {name}")

• user knows that the code expects input of type str
• the same about output

3 main categories of docstrings

If comment_size > 72 characters:

use `multiple line comment`

Docstring conventions

Multi-line docstring example:

"""This is the summary line

This is the further elaboration of the docstring. Within this section,
you can elaborate further on details as appropriate for the situation.
Notice that the summary and the elaboration is separated by a blank new
line.

# Notice the blank line above. Code should continue on this line.

Example of using __doc:

Code (version 1):

def say_hello(name):
    print(f"Hello {name}, is it me you're looking for?")

say_hello.__doc__ = "A simple function that says hello... Richie style"

Code (alternative version):

def say_hello(name):
    """A simple function that says hello... Richie style"""
    print(f"Hello {name}, is it me you're looking for?")

Input:

>>> help(say_hello)

Returns:

Help on function say_hello in module __main__:

say_hello(name)
    A simple function that says hello... Richie style

init

Docstrings in scripts

You can always facilitate documentation with tools.

(check the table below)

Multiple purposes of commenting:

• planning and reviewing code - setting up a code template
• code description
• algorithmic description - for example, explaining the work of an algorithm or the reason of its choice
• tagging - BUG, FIXME, TODO

Commenting code:

• describing code to/for developers
• help to guide the reader to better understand your code, its purpose/design

Recommended videos to start documenting

(check the list below)

argparse

Different docstring formats:

• Google docstrings (not a formal specification)
• reStructured Text
• NumPy/SciPy docstrings
• Epytext

Public and Open Source Python projects should have the docs folder, and inside of it:

• Tutorials
• How-To Guides
• References
• Explanations

(check the table below for a summary)

dir() function examines directory of Python objects. For example dir(str).

Inside dir(str) you can find interesting property __doc__

Docstrings - built-in strings that help with documentation

help() function.

After typing help(str) it will return all the info about str object

project_root/
│
├── project/  # Project source code
├── docs/
├── README
├── HOW_TO_CONTRIBUTE
├── CODE_OF_CONDUCT
├── examples.py

(private, shared or open sourced)

Think only about """ when using docstrings

TSDoc <--- TypeScript comment syntax. You can create documentation with TypeDoc

mkdocs for diagrams seems cool. :)

https://github.com/UnlockedEdu/documentation-pipeline-generator

Hard to find documentation that has this list. Source code as docs it is!

See also: https://developer.wordpress.org/themes/functionality/internationalization/, which is parallel to this page except for themes.

I like how they have indexed their core code base so they can show in both directions:

• which other core functions a function uses
• which other core functions use this function (references)

This is a nice conference report, but are there any slides or recordings available from the event as well?

I assume this is for the master branch, and https://neutrinojs.org/ is for the latest released version.

Difference between tutorials, how-to guides, explanation and reference:

Beschreibung

Durch Folgen der URI gelangt man zu einer Einzelansicht für das Exemplar. Die dort angezeigten Daten sind ebenfalls als JSON-LD verfügbar. Siehe [Link](##### Beschreibung

Durch Folgen der URI gelangt man zu einer Einzelansicht für das Exemplar. Die dort angezeigten Daten sind ebenfalls als JSON-LD verfügbar. Siehe Link für die markierte Ressource.

How to document

Name

Spezieller Organisationstyp

Beschreibung

Diese Klassifikation liefert eine granulare Unterscheidung verschiedener Einrichtungstypen. Das verwendete SKOS-Schema basiert auf der Klassifikation des deutschen ISIL-Verzeichnis.

Abdeckung

Zu jeder Institution wird der detaillierte Typ angegeben.

Verwendungsbeispiele

Auflistung aller Bibliotheken, die als Wissenschaftliche Spezialbibliothek klassifiziert sind.

URI

http://www.w3.org/ns/org#classification

Name

Region key

Description

The key of the administrative area the organization is located in.

Coverage

Only applies to organizations in Germany. Currently missing in more than 2000 entries of institutions in Germany.

Use cases

• Organizations in Schleswig-Holstein: http://lobid.org/organisations/search?q=rs:01*
• Organizations from district Peine: http://lobid.org/organisations/search?q=rs:03157*

URI

http://purl.org/lobid/lv#rs

Alle Titel der Nordrhein-Westfälischen Bibliographie (NWBib) beinhalten folgendes Datum: "inCollection.id": "http://lobid.org/resources/HT014176012#!"

Zur Einschränkung einer API-Abfrage auf das NWBib-Subset muss die Abfrage entsprechend hiermit ergänzt werden: inCollection.id:"http://lobid.org/resources/HT014176012#!".

Beispiel: Alle Titel der NWBib mit "Köln" im Titel:

title:Köln AND inCollection.id:"http://lobid.org/resources/HT014176012#!"

WHERE >> AGGREGATE >> HAVING (use aggregate functions)

this is SQL procedural sequence on data querying.

and yes HAVING kind of do almost the same thing in WHERE. but it accepts the grouping and aggregation functions that fails to be in WHERE.

Name: Weitere Profile

Beschreibung: Profile des Dienstes in sozialen Netzwerken wie Twitter, Instagram, GitHub etc.

Pflichtfeld?: nein

Typ: Array, URL

Name: Lizenz(en)

Beschreibung: Die Lizenz(en), unter denen die angebotenen Inhalte veröffentlicht sind. Angegeben werden die URL zur Lizenz

Pflichtfeld?: nein

Typ: Array, URL

Name: Änderungsdatum

Beschreibung: Das letzte Änderungsdatum der Visitenkarte

Pflichtfeld?: ja

Typ: Date, Format ISO 8601

Name: Link zum genutzen Schema

Beschreibung: Link zur genutzen Version des Schemas für dei Validierung der Visitenkarte

Pflichtfeld?: ja

Typ: URL

Name: Schnittstellentyp

Beschreibung: Die Art der maschinellen Schnittstelle

Pflichtfeld?: nein

Typ: String

Beispielewerte: Search, Sitemap, OAI-PMH, Statistics, embed (oEmbed), Generic_Api

Name: Schnittstellendokumentation

Beschreibung: Ein Link zur Dokumentation der Schnittstelle

Pflichtfeld?: nein

Typ: URL

Name: API-Endpoint

Beschreibung: Der URL des Schnittstellen-Endpunkts

Pflichtfeld?: nein

Typ: URL

Name: Typ des Objekts

Beschreibung: Angabe der Typen ServiceChannel und WebAPI

Pflichtfeld?: nein

Typ: Array, URL

Werte: ServiceChannel, WebAPI

Name: Ort

Beschreibung: Der name des Ortes, in dem der Betreiber sitzt.

Pflichtfeld?: nein

Typ: String

Name: Postleitzahl

Beschreibung: Die Postleitzahl des Sitzes des betreibers

Pflichtfeld?: nein

Typ: Integer

Name: Straße

Beschreibung: Die Straße, in der der Betreiber sitzt

Pflichtfeld?: nein

Typ: String

Name: Land

Beschreibung: Das Land, in dem der Betreiber sitzt

Pflichtfeld?: nein

Typ: String

Werte: ISO 3166-1 Codes

Name: Typ des Objekts

Beschreibung: Angabe des Typs PostalAddress

Pflichtfeld?: ja

Typ: URL

Wert: PostalAddress

Name: Typ des Objekts

Beschreibung: Angabe des Typs GeoCoordinates

Pflichtfeld?: ja

Typ: URL

Wert: GeoCoordinates

Name: Adresse

Beschreibung: Die Adresse der Anbieters

Name: Geographische Breite

Pflichtfeld?: nein

Typ: Nummerischer Wert

Name: Geographische Länge

Pflichtfeld?: nein

Typ: Nummerischer Wert

Name: Geokoordinaten

Beschreibung: Dieses JSON-Objekt beinhaltet die Angaben zur Geoposition der Einrichtung nach WGS 84.

Pflichtfeld?: nein

Typ:

Name: Standort

Beschreibung: Im location-Objekt befinden sich Angaben zum Sitz des Anbieters: Anschrift und Geokoordinaten.

Pflichtfeld?: nein

Typ: Objekt

Name: Typ des Objekts

Beschreibung: Angabe des Typs Place

Pflichtfeld?: ja

Typ: URL

Wert: Place

Name: E-Mail-Adresse des Anbieters

Beschreibung: Die E-Mail-Adresse des Anbieters

Pflichtfeld?: nein

Typ: Text (Format)

Name: Typ des Anbieters

Beschreibung: Angabe, ob der Anbieter eine Organisation oder Gruppe (Organization) oder eine Einzelperson (Person) ist. Pflichtfeld?: ja

Typ: Array, URL

Mögliche Werte: Organization, Person

Name: Name des Anbieters

Beschreibung: Der Name des Dienstanbieters

Pflichtfeld?: ja

Typ: String

Name: Anbieter des Dienstes

Beschreibung: Die Organisation, Gruppe oder Einzelperson, die den Dienst anbietet

Pflichtfeld?: ja

Typ: Array, Objekt

Felder: type (Pflicht), name (Pflicht), email, location, id

Name: Schnittstellen des Dienstes

Beschreibung: Angabe von Maschninenschnittstellen zum Dienst, deren Art und Dokumentation.

Pflichtfeld?: ja

Typ: Array, Objekt

Felder: type (Pflicht), serviceURL (Pflicht), serviceType, documentation

Name: Launch-Datum

Beschreibung: Das Datum, an dem der Dienst offiziell gelauncht wurde

Pflichtfeld?: nein

Typ: Date, Format ISO 8601

Name: Zugangsfreiheit

Beschreibung: Ist die Nutzung des Dienstes ohne Zugangsbeschränkungen (Registrierung, Authentifizierung) möglich und die Inhalte ohne Einschränkungen erreichbar?

Pflichtfeld?: nein

Typ: Boolean

Name: Fach/Thema der Inhalte

Beschreibung: Die Fächer bzw. Themen, zu denen der Dienst Open Educational Resources (OER) anbietet. Die Werte sollten URLs aus einer kontrollierten Liste sein.

Pflichtfeld?: nein

Typ: Array, URL

Name: Zielgruppe(n) des Angebotes

Beschreibung: Die Zielgruppe, auf der das Angebot des Dienstes ausgerichtet ist.

Pflichtfeld?: nein

Typ: Array, URL

Werteliste: http://purl.org/dcx/lrmi-vocabs/educationalAudienceRole/

Name: Art des Dienstes

Beschreibung: Die Art des Dienstes

Pflichtfeld?: ja

Typ: Array, String

Beispielwerte: Repository, Referatory, Wiki, LMS

Name: URL als Identifiktator

Beschreibung: Die URL, durch den der Dienst identifiziert wird. Das ist in der Regel die Homepage. Auf dieser URL MUSS die Visitenkarte später findbar / abrufbar sein

Pflichtfeld?: ja

Typ: URL

Name: Name des Dienstes

Beschreibung: Der Name des OER-Services

Pflichtfeld?: ja

Typ: String

Name: Beschreibung des Dienstes

Beschreibung: Eine kurze Beschreibung des Dienstes.

Pflichtfeld?: nein

Typ: String

Name: Sprache(n) des Hauptangebotes

Beschreibung: Die Sprachen der Open Educational Resources (OER), die der Dienst anbietet.

Pflichtfeld?: nein

Typ: Array, String

Name: Icon des Dienstes

Beschreibung: Ein Link zu einer Bilddatei mit einem Icon des Dienstes, das etwa zur Kennzeichnung von Einträgen in einer Suchergebnisliste genutzt werden kann. Die verlinkte Datei sollte im Format svg oder png sein und eine Größe von 64x64px haben.

Pflichtfeld?: nein

Typ: URL

Dateiformat: Das verlinkte Bild sollte eine svg- oder png-Datei sein mi8t 64x64px.

Name: Logo des Dienstes

Beschreibung: Ein Link zu einer Bilddatei mit dem Logo des Dienstes.

Pflichtfeld?: nein

Typ: URL

Name: JSON-LD-Kontext (@context)

Beschreibung: @context ist ein JSON-LD-Keyword, mit dem das JSON-LD-Kontext-Dokument angegeben wird. Es beinhaltet ein Mapping von JSON Keys auf RDF-Properties und von Typen auf RDF-Klassen. Mit dem JSON-LD-Kontext kann aus dem angebotenen JSON, RDF generiert werden.

Pflichtfeld?: ja

Typ: URL

Wert: http://schema.org/

Name: Typ

Beschreibung: Mit type wird der Typ der durch die Visitenkarte beshriebenen Ressource angegeben. Der Typ wird durch eine URL identifiziert. Durch Nutzung des schema.org-Kontexts lassen sich die URLs kürzen, anstatt http://schema.org/WebSite und http://schema.org/Service können WebSite und Service angegeben werden.

Pflichtfeld?: ja

Typ: Array, URL

Werte: WebSite, Service

Above is because of the nature of Streams in general: they are lazily executed (or put another way, execution is delayed until the latest convenient method call).

Name

Change date

Description

The date when the resource description was last changed.

Coverage

80 % of the records have a change date, while it is missing for 20 %, see here for a pie chart.

Usage examples

• Get all records changed in 2017: http://es.labs.lobid.org/loc-work-20181119-141239/_search?q=adminMetadata.changeDate:[2017-01-01%20TO%202017-12-31]
• Get all records changed until 2017: http://es.labs.lobid.org/loc-work-20181119-141239/_search?q=adminMetadata.changeDate:[*%20TO%202016-12-31]

URI

http://id.loc.gov/ontologies/bibframe/changeDate

The label for the work.

Combines the title.mainTitle and title.subtitle fields. This field is set for 98 of 100 works in our test set. It can be queried in a field query with label:*.

It is mapped to rdf-schema#label in our context.

Name

ISIL

Beschreibung

Der ISIL (International Standard Identifier for Libraries and Related Organizations) der Einrichtung. Das deutschsprachige ISIL-Verzeichnis ist – neben der Deutschen Bibliotheksstatistik (DBS) – die Datenquelle von lobid-organisations.

Abdeckung

Alle Einträge aus dem ISIL-Verzeichnis haben einen ISIL, das sind etwa 14000 Einträge.

Verwendungsbeispiele

In der bibliothekarischen Arbeit begegnet man desöfteren ISILs. Mit einem lobid-organisations-Lookup kann einfach und zügig die dadurch identifizierte Institution gefunden werden.

URI

http://purl.org/lobid/lv#isil

Name

Art des Unterhaltsträgers

Beschreibung

Typ des Unterhaltsträgers der Einrichtung. Die Werte stammen aus einem kontrollierten Vokabular, siehe das SKOS-Schema.

Abdeckung

Vorhanden bei gut 7000 Einträgen, fehlt bei ca. 7.700

Verwendungsbeispiele

• Anteil der von der katholischen Kirche finanzierten Bibliotheken in NRW an der Gesamtzahl der NRW-Bibliotheken (~1:2) vs. Anteil der von der katholischen Kirche finanzierten Bibliotheken in Bayern an der Gesamtzahl der bayerischen Bibliotheken (~1:2)

URI

http://purl.org/lobid/lv#fundertype

Name

Allgemeiner Organisationstyp

Beschreibung

Art der Einrichtung. Vergebene Typen sind: Bibliothek (Library), Archiv (Archive), Museum (Museum), Verlag (Publisher), sonstige Organisationen (Organization).

Abdeckung

Jeder Eintrag ist einem Einrichtungstyp zugeordnet.

Verwendungsbeispiele

• Einrichtungen vom Typ Bibliothek, Archiv, Museum
• Einrichtungen aus Nordrhein Westfalen vom Typ Museum

Provenienz

Für Einträge aus der DBS wird automatisch der Typ "Library" vergeben. Bei den Einträgen aus dem Sigelverzeichnis wird der Typ auf Basis der detaillierten Organisationsklassifikation verwendet, siehe das Mapping der Notationen auf einen Typ.

URI

"type" ist auf das JSON-LD-Keyword "@type" gemappt, das in diesem Zusammenhang (als node type) in RDF mit http://www.w3.org/1999/02/22-rdf-syntax-ns#type übersetzt wird.

Name

Erstellungsdatum

Beschreibung

Enthält das Datum an dem die Ressource erfasst wurde oder durch Fremddatenübernahme in den Katalog kam im Format jjjjmmtt.

Verwendungsbeispiele

• Einschränken einer Suche auf Titel, die nach der RDA-Einführung im hbz-Verbund (1.1.2016) ergänzt wurden: https://lobid.org/resources/search?q=bibliothek+AND+describedBy.dateCreated:%3E20160101

Abdeckung

Ca. 800 Ressourcen haben kein Erstellungsdatum, d.h. sie wurden nie angelegt. ;-)

Provenienz

MAB2 Feld 002

URI

http://purl.org/dc/terms/created

Name

Bearbeitungsdatum

Beschreibung

Enthält das Datum, an dem das Katalogisat zum letzten Mal bearbeitet wurde im Format jjjjmmtt.

Abdeckung

Ca. 12 Millionen Ressourcen haben kein Bearbeitungsdatum, das heißt die Katalogeinträge wurden nach ihrer Erstellung nicht mehr angefasst.

Verwendungsbeispiele

• Eine Liste aller Ressourcen, die am 1. April 2016 das letzte Mal verändert wurden: https://lobid.org/resources/search?q=*+AND+describedBy.dateModified:20160401

Provenienz

MAB2-Feld 003

URI

http://purl.org/dc/terms/modified

Name

Ist Teil von

Beschreibung

Enthält Informationen zum Erscheinen der Ressource als Teil eines übergeordneten Werks (eines, mehrbändigen Werks, einer Serie oder eines Periodikums).

Abdeckung

Gut sieben Millionen Einträge sind Teil eines übergeordneten Werkes.

Verwendungsbeispiel

Asterix-Bände der "Mundart"-Reihe in kölschem Dialekt

URI

http://purl.org/lobid/lv#isPartOf

Name

ZDB-ID

Beschreibung

Enthält die ZDB-ID (aus dem MAB2-Feld 025z).

Abdeckung

Enthalten bei ca. 1,8 Mio. Einträgen. Bei ca. 1,8 Mio.), enthalten, fehlt bei ca. 270.000) (Stand: Februar 2018).

Verwendungsbeispiel

Die Lokalausgabe einer Zeitung ohne ISSN finden (z.B. die Ausgabe für Enger und Spenge der Zeitung Neue Westfälische).

URI

http://purl.org/lobid/lv#zdbID

Name

Erscheinungsdatum

Beschreibung

Enthält das Erscheinungsjahr bzw. bei Publikationen mit Erscheinungsverlauf den Beginn des Erscheinens.

Abdeckung

Enthalten bei über 18,5 Millionen Einträgen, fehlt bei mehr als 1,7 Millionen (Stand: Februar 2018).

Verwendungsbeispiel

Publikationen zur allgemeinen Suche "Bibliothek" seit 2013

MAB-Felder

Stammt aus dem MAB2-Feld 425, 419, 595 oder 089.

URI

http://schema.org/startDate

Name

Erscheinungsfrequenz / Periodizität

Beschreibung

Enthält die Erscheinungsfrequenz eines Periodikums unter Nutzung des kontrollierten Vokabulars MARC21-008: Frequency of continuing resource.

Vorkommen

Über 400.000 Einträge besitzen eine Angabe zur Erscheinungsfrequenz, bei mehr als 1,5 Millionen Periodika fehlt eine Angabe zur Erscheinungsfrequenz (Stand: Februar 2018).

MAB-Felder

Stammt aus dem MAB2-Feld 523.

URI

http://id.loc.gov/ontologies/bibframe/frequency

Name

ISSN

Beschreibung

Enthält die ISSN (International Standard Serial Number).

Vorkommen

Ca. 373.000 Einträge besitzen eine ISSN (Stand: Februar 2018).

Beispiel

Unter den vielen anderen Ausgaben die regelmäßig erscheinende Frankfurter Allgemeine Zeitung finden.

MAB-Felder

Stammt aus dem MAB2-Feld 542.

URI

http://purl.org/ontology/bibo/issn

Name

Angaben zur übergeordneten Publikation

Beschreibung

Dieses Feld findet sich hauptsächlich bei Aufsätzen. Es enthält bibliographischen Angaben zur Ressource, in der der Aufsatz enthalten ist.

Abdeckung

Enthalten bei ca. 953.000 Einträgen, fehlt bei ca. 27.500 Aufsätzen (Stand: Februar 2018).

MAB-Felder

Stammt aus dem MAB2-Feld 525 bzw. wenn nicht vorhanden, zusammengesetzt aus den Feldern 590-593, 596 und 598.

URI

http://purl.org/dc/terms/bibliographicCitation

Name

Titel

Beschreibung

Titel der Ressource

Abdeckung

Es gibt ca. 1.827 Einträge, die keinen Titel besitzen (Stand: Februar 2018).

Beispiel

Suche nach Werken mit "Schwimmen" und "Essen" im Titel.

MAB-Felder

Stammt aus dem MAB2-Feld 310 bzw. wenn nicht vorhanden, aus den Feldern 331 oder 333.

URI

http://purl.org/dc/terms/title

Name

Inhaltsverzeichnis

Beschreibung

Link zu einem digitalisierten Inhaltsverzeichnis der Ressource.

Abdeckung

Mehr als 1,4 Millionen Ressourcen haben einen Link zu einem Inhaltsverzeichnis (Stand: Februar 2018).

MAB-Felder

Stammt aus dem MAB2-Feld 655, Indikator e, Unterfeld u, insofern in 655.e, Unterfeld x oder 3 angegeben ist, dass es sich um ein Inhaltsverzeichnis handelt (siehe den relevanten Teil der Morph-Datei).

URI

http://purl.org/dc/terms/tableOfContents

Name

Siehe auch

Beschreibung

Enthält einen Link zu weiteren nicht näher definierten Informationen über die Ressource (z.B. Inhaltsverzeichnis).

Abdeckung

Gute 219.000 Einträge besitzen Informationen in diesem Feld (Stand: Februar 2018).

MAB-Felder

Stammt aus dem MAB2-Feld 655, Indikator e, Unterfeld u.

Name

Erscheinungsort

Beschreibung

Enthält die Angabe der Erscheinungsorte in unkontrollierter Form (siehe etwa das Kürzel u.a.).

Abdeckung

Enthalten bei ca. 18,1 Mio. Einträgen, fehlt bei ca. 2 Mio..

Provenienz

Stammt aus den MAB2-Feldern 410, 415, 419 oder 594.

URI

http://schema.org/location

Name

Publikationsereignis / Publikationsverlauf

Beschreibung

Enthält ein Objekt PublicationEvent mit Angaben zum Publikationsereignis bzw. zum Publikationsverlauf.

Verwendungsbeispiel

Publikationen des Kölner Taschen-Verlags aus dem Jahr 2016.

Abdeckung

Fehlt bei weniger als 200.000 Ressourcen.

URI

http://schema.org/publication

Name

Art des Inhalts

Beschreibung

Enthält genaure Informationenzur Art des Inhalts unter Nutzung kontrollierter Werte aus der GND, siehe die Liste. Vorhanden bei neuen Einträgen ab Ende 2015.

Abdeckung

Vorhanden bei ca. 250.000 Ressourcen (Stand: Februar 2018).

MAB-Felder

Stammt aus dem MAB-Feld 064.

URI

http://rdaregistry.info/Elements/u/P60584

Name

Sprache

Beschreibung

Die Sprache, in der eine Ressource verfasst ist, identifiziert anhand der URI beim Normvokabular der LoC mit Angabe der deutschsprachigen Benennung.

Abdeckung