Voor wie

API-documentatie opslaan met de code heel

Clean Clipper leest de taal van een codeblok van de pagina zelf af – uit de class op de fence, uit het bovenliggende element of uit de markup van de highlighter – en schrijft die in de Markdown. Op een technisch corpus bleef het label staan in 73 van de 156 fences, tegen 20 en 0 bij de twee vergeleken engines.

Waar documentatie ophalen misgaat

Documentatie bestaat grotendeels uit code, en juist dat deel laten de meeste clippers vallen. Je haalt een pagina van een framework op, plakt hem in je notities en krijgt een muur grijze tekst terug: de fences staan er nog, maar kaal. Welke regels JavaScript waren en welke shell moet je uit je hoofd reconstrueren. Bij drie snippets valt dat mee, bij dertig pagina’s niet.

Wat eromheen staat gaat net zo hard mis. Een parametertabel waarin één cel een codevoorbeeld bevat, klapt bij een generieke omzetter dicht tot één regel of verdwijnt helemaal. De navigatiebalk en de versiekiezer komen juist wél mee, want die zitten in dezelfde container als de tekst. Het opruimen kost dan meer tijd dan het opzoeken.

Het derde probleem is het openstaande tabblad zelf. Documentatie heeft versies, het adres meestal niet: de pagina die je voor v4 las wordt stilletjes v6, met een hernoemde vlag en een geschrapte optie, en je bladwijzer werkt nog – alleen wijst hij naar andere tekst. Nergens in je aantekeningen staat tegen welke versie je destijds hebt gebouwd. Een bestand met de URL en de datum die de pagina zelf opgaf beantwoordt die vraag een jaar later; een bladwijzer heeft dat nooit gekund.

Wat er in de notitie belandt

• Een fence komt eruit als ```js en niet kaal – highlighting werkt in Obsidian, VS Code en op GitHub zodra je plakt
• Het label komt van de pagina zelf: de class die de highlighter achterliet, geen gok op basis van de code
• Tabellen met een codevoorbeeld in een cel klappen niet dicht tot één regel
• Navigatiebalken, versiekiezers en “op deze pagina”-blokken worden weggeknipt in plaats van omgezet
• Nul achtergebleven HTML-tags over 512 gemeten pagina’s – geen div midden in een fence
• README’s op GitHub, antwoorden op Stack Overflow en framework-documentatie waren het eerste testcorpus
• Verwijzingen worden [^1]-voetnoten met hun definities achterin, dus de bronvermeldingen van een specificatie werken binnen de notitie nog
• Het veld extraction noteert welke weg is gebruikt: dom, of jsonld-articlebody als de pagina haar tekst alleen in gestructureerde data had staan

Een verzoek aan het register geeft een antwoord in JSON terug:

```json
{
  "naam": "Gemeente Amsterdam",
  "identificatie": "0363",
  "provincie": "Noord-Holland"
}
```

## Stap 2: foutafhandeling en statuscodes

Instellen voor documentatie

Eén keer vijf minuten, daarna doet de sneltoets het werk. De standaardinstellingen zijn gemaakt om artikelen te lezen; documentatie wil een andere bestandsnaam, geen auteursveld en geen afbeeldingen.

1. Installeer de extensie en zet het icoon vast in de werkbalk. Klik met rechts op het icoon en kies Opties; de instellingen openen in een tabblad.
2. Zet wat een klik op het icoon doet op “opslaan in map”. Dat maakt van een clip één toetsaanslag zonder venster ertussen – het voorbeeldvenster helpt zolang je het gereedschap leert kennen en zit daarna in de weg.
3. Kies de map. Wijs een directory aan die je toch al in versiebeheer hebt, bijvoorbeeld docs/clips in de repository waar je aan werkt. De browser vraagt één keer bevestiging en onthoudt die voor dit profiel.
4. Zet het sjabloon voor de bestandsnaam op {domain}-{title}. Vier frameworks hebben allemaal een pagina “Aan de slag”, en zonder het domein in de naam wordt de vierde geruisloos aan-de-slag-4.
5. Laat in de frontmatter source en extraction aan staan en zet author uit. Documentatie is zelden ondertekend, en een leeg veld in elk bestand is ruis die je later alsnog weghaalt.
6. Zet afbeeldingen op overslaan. Een schermafbeelding van andermans editor is niet doorzoekbaar, en de link wijst naar een CDN dat verhuist.
7. Open chrome://extensions/shortcuts en controleer dat Alt+Shift+M eraan hangt. Heeft een andere extensie de combinatie ingepikt, dan pak je hem daar terug.

Instellingen voor ontwikkelaars

Dit zijn de waarden die je van de standaard wilt afwijken, met de reden waarom die keuze juist voor documentatie uitmaakt en niet voor lezen in het algemeen.

Start de migratie voordat je de service herstart:

```
php artisan migrate --force
systemctl restart api
```

De fence komt kaal binnen. De pagina zet de kleuren met eigen CSS en laat geen
enkele class achter waaruit de taal valt af te leiden, dus er valt niets te
lezen. Een gegokt `bash` zou hier toevallig kloppen en op de volgende pagina
`sql` verven alsof het shell was.

Drie werksessies

Vastleggen tegen welke versie je hebt gebouwd

Je staat op de v4-tak van de documentatie van een framework, bij de pagina over een configuratievlag die in v5 is hernoemd. Je drukt op Alt+Shift+M. Het bestand belandt als voorbeeld-dev-configuratie.md in docs/clips, met source naar het /v4/-adres en de datum die de pagina zelf opgaf.

Acht maanden later gedraagt die vlag zich anders in productie en weet niemand meer waarom hij zo stond. De clip zit in de repository, in dezelfde reeks commits als de wijziging, en zegt tegen welke versie van de documentatie het besluit is genomen. Het adres serveert inmiddels v6 en noemt de vlag helemaal niet meer.

De forumdraad die het echt oploste

De officiële documentatie beschrijft het gelukkige pad; de oplossing voor jouw geval staat vier reacties diep in een forumdraad, waar het juiste antwoord op 31 punten staat onder een verkeerd antwoord op 12. Je haalt de draad op. De regel voor die site stuurt hem naar draden, en de reactiestructuur komt binnen als geneste blockquotes met de score erbij.

Die score is precies het deel dat telt bij het teruglezen. Een platte kopie van dezelfde draad verliest de ordening volledig, en dan zit je vijf meningen te herlezen zonder aanwijzing welke de gemeenschap gelijk gaf.

Een tabel met omgevingsvariabelen, rechtstreeks in een pull request

De deploy-handleiding heeft een tabel met achttien omgevingsvariabelen, waarvan er drie een codevoorbeeld in de cel hebben staan. Je selecteert de tabel op de pagina, haalt de selectie op en plakt de Markdown in de beschrijving van je pull request. GitHub toont hem als tabel, want het is een GFM-tabel en geen schermafbeelding.

Op het technische corpus van vijftien tabellen hield deze serialisatie er twaalf heel, waar de vergeleken engines er elk zeven hielden. De cellen waarop generieke omzetters stuklopen zijn juist deze: die met code of een lijst erin.

Tegenover de gebruikelijke manieren

Elk van deze manieren werkt, en op elk team is er iemand die het zo doet. De derde kolom is de eerlijke prijs – ook die van ons.

Als het er niet goed uit komt

Waarom staat er geen taal op mijn code-fence?

Omdat de pagina niet zei welke taal het was. Clean Clipper leest de taal af van de class die de highlighter van de site achterliet; het kijkt niet naar de code om te gokken. Een met de hand opgemaakt voorbeeld zonder class geeft een kale fence, en dat is de eerlijke uitkomst: een gegokt python op een shell-snippet is erger dan geen label, want dan kleurt de highlighting overtuigend de verkeerde dingen.

Waarom mist de helft van de handleiding?

Bijna altijd tabbladen of een accordeon. De extensie zet om wat de browser echt heeft gerenderd, en een tabblad waarvan de inhoud pas bij een klik wordt ingeladen staat tot dat moment niet in de DOM. Klap het open en haal dan op, of haal per variant een clip. Sites die alle tabbladen renderen en met CSS verbergen, leveren ze allemaal, achter elkaar.

Waarom zegt hij dat er geen artikel is?

Een API-speeltuin, een zoekresultaat of een pakketindex bestaat vooral uit linkteksten, en die weigert de extensie met opzet: zit meer dan ongeveer een kwart van de tekens in links, dan meldt ze “geen artikel” in plaats van je driehonderd regels te geven. Op de gemeten Europese corpora lag het aandeel links bij echte artikelen tussen 0,036 en 0,064 – een overzichtspagina zit daar een orde van grootte boven.

Wat betekent extraction: "jsonld-articlebody" in mijn bestand?

Dat de pagina haar tekst wel in gestructureerde data meestuurde, maar hem nooit in de DOM heeft uitgerenderd, dus is de tekst daaruit gelezen. Dat wordt genoteerd en niet verzwegen, want de twee wegen kunnen verschillen: de versie in de gestructureerde data is soms een eerdere opzet en soms juist de enige volledige. Zie je die waarde staan, kijk dan even naar het origineel voordat je op de tekst leunt.

Wat het niet doet

Er zit geen crawler in: je haalt één pagina tegelijk op, de pagina waar je zelf op staat. Het label op een fence is precies zo goed als de bronpagina – geeft een site zijn code geen taal mee, dan verzint de extensie er ook geen. Diagrammen en schermafbeeldingen blijven links naar de oorspronkelijke site; binaire bestanden worden niet gedownload. En op pagina’s die de browser afschermt, zoals chrome:// en de extensiestore zelf, draait de extensie niet.

Vragen