La communauté OpenJDK a proposé la JEP-413 comme moyen d'ajouter des extraits de code source compilables à la documentation de l'API. Cette approche simplifiera le rôle des responsables qui travaillent sur leurs exemples ainsi que des lecteurs qui souhaitent copier du code opérationnel.
L'approche de compilation de code sous forme d'extraits de documentation est déjà utilisée dans des projets majeurs tels que le SDK Azure, le langage R, NetBeans et GraalVM. Les développeurs travaillant sur des projets personnalisés avec de la documentation peuvent tirer parti d'un projet existant de l'architecte NetBeans Jaroslav Tulach, CodeSnippet4Javadoc.
Le responsable du projet GraalVM Thomas Wuerthinger a déclaré : "C'est une excellente initiative ! Nous utilisons actuellement une solution développée sur mesure pour créer des extraits de code dans notre documentation GraalVM ... "
La conversation a identifié un point commun dans les grands projets de développement pour discuter de la manière dont de nombreux projets sont arrivés sur une solution similaire pour afficher et surveiller les erreurs dans leur documentation. «Nous faisons la même chose avec le SDK Azure», a déclaré Jonathan Giles, Principal Java Architect chez Microsoft qui travaille sur le SDK Azure. "J'ai hâte de passer un jour à cela si cela fonctionne comme un remplacement approprié." JEP signifie Java Enhancement Proposal, ce qui signifie qu'un vote sur la proposition et une intégration de suivi sont nécessaires pour que le projet soit intégré dans l'écosystème Java.
L'avantage des extraits de code source compilables peut avoir un impact sur les développeurs qui lisent la documentation, puis utilisent l'exemple de code fourni dans leurs propres projets. La tendance des développeurs à copier + coller du code est bien connue dans l'industrie, où StackOverflow a publié une parodie clavier pour le poisson d'avril 2021 avec trois touches : ctrl, c et v. La blague parodie les raccourcis clavier copier / coller et s'ouvre avec le slogan "Les bons artistes copient. Les grands artistes volent. Les plus grands artistes copient, puis collent."
Une quantité importante de recherches a été consacrée à la documentation des API et aux moyens de détecter les erreurs ou les appels obsolètes. Les chercheurs Seonah Lee, Rinxin Wu, Shing-Chi Chueng et Sungwon Kang ont publié des recherches similaires via l'IEEE sur l'outil FreshDoc, qui analyse et détecte la documentation d'API obsolète. Dans une étude analysant l'efficacité de l'analyse de la documentation, leur article déclare : "Lorsque nous avons signalé 40 noms d'API obsolètes … les développeurs ont accepté 70% des suggestions."
Le texte de la JEP-413 explique que le but est de simplifier la façon dont les développeurs peuvent créer la documentation du code, mais cela n'arrêtera pas toutes les erreurs possibles. Par exemple, le JEP ne compilera pas le code; les développeurs devraient plutôt intégrer leurs extraits de code avec CI / CD pour valider le code avant l'extraction. Ce processus permet de ne pas inclure les instructions standard, comme les instructions d'importation, dans la documentation, mais reste facilement disponible pour tous ceux qui souhaitent les consulter.
Si le vote de la JEP réussit, les fonctionnalités seront ajoutées à une future version des outils de documentation Java qui aident à marquer et à créer la documentation. Un vote réussi aurait le plus d'impact sur les outils de documentation d'API tels que JavaDoc et ne remplacerait pas la tendance commune des guides de mise en route qui présentent aux nouveaux programmeurs ce que fait l'API et où chercher dans un projet pour trouver des API particulières.