Javadoc care se simte ca site-ul tău

Codename One, un framework open-source ce permite dezvoltarea de aplicații native dintr-o singură bază de cod Java sau Kotlin, a rezolvat o problemă de lungă durată legată de documentația API. Anterior, navigarea prin linkurile Javadoc conducea utilizatorii către un site cu un aspect și o senzație diferite față de site-ul principal, creând o experiență fragmentată. Soluția a implicat crearea unui nou doclet, `maven/javadoc-hugo-doclet`, care separă sarcina generării datelor API de redarea site-ului. Acest modul transmite acum modelul API, inclusiv tipuri, semnături și arbori de documentație, către Hugo, permițând șabloanelor site-ului să redea conținutul cu aceeași temă și tipografie ca ghidul pentru dezvoltatori și blogul.

Implementarea tehnică valorifică comentariile de documentație Markdown din Java, introduse în JDK 23, permițând dezvoltatorilor să scrie documentație în format Markdown direct în codul lor. Noul doclet procesează aceste noduri Markdown și le transmite către renderer-ul Goldmark al lui Hugo. În plus, a fost dezvoltat un component `MarkdownSections` pentru a recunoaște și extrage date structurate din anteturi Markdown convenționale, cum ar fi 'Parameters' și 'Returns', care sunt apoi redate ca tabele, în timp ce alte anteturi rămân în text. Funcționalitatea de căutare API a fost, de asemenea, optimizată, indexând identificatori și segmente camel-case pentru a oferi o experiență de căutare mai eficientă, care grupează membrii API pe tip.

Această abordare asigură că documentația API este integrată perfect în site-ul principal, oferind o experiență unificată pentru dezvoltatori, fără a sacrifica capacitatea de a genera o arhivă standard `javadocs.zip` pentru utilizare offline. Proiectul subliniază, de asemenea, importanța păstrării linkurilor existente prin compararea noii redări cu mii de fragmente vechi pentru a identifica și remedia potențiale probleme cu ancore, generice și membri moșteniți. Această metodologie oferă un șablon valoros pentru alte proiecte Java care doresc să-și integreze mai eficient documentația API cu prezența lor web principală.