Generarea documentației – FiM++ (Inginerie software, Limbaje De Programare, Design Lingvistic, Generarea Documentației)

Iepurele de sud a intrebat.

Aceasta este o întrebare pe care am pus-o inițial pe Stack Overflow, dar ca o întrebare de proiectare conceptuală, spre deosebire de o problemă tehnică, cred că ar putea fi mai potrivită sau, eventual, ar putea avea o valoare paralelă alternativă, pe acest forum.

Structura unui program FiM++ cere ca acesta să se încheie cu închiderea unei litere și cu numele autorului codului într-un mod specific.

Dear Princess Celestia and Stack Exchange and String: A Sample:
    ...
Your faithful student, Southpaw Hare!

În conformitate cu specificația limbajului, , cuvântul cheie „Your faithful student,” (inclusiv virgula și spațiul care urmează) este utilizat ca etichetă de sfârșit pentru definițiile de clasă, iar numele care urmează este un comentariu fără efect sintactic.

Faptul că autorul este inclus automat (dacă nu este strict necesar) în fiecare fișier mă face să mă întreb dacă poate fi folosit ca o formă de documentație interpretabilă asemănătoare cu Java Docs. Cu alte cuvinte, că alte programe sau editoare ar putea să analizeze acest nume și să-l folosească într-un anumit mod.

  1. Care este cerința unei astfel de documentații interne bazate pe comentarii? Există ceva în acest tip special de sintaxă care ar putea cauza probleme?

  2. Este cuvântul cheie suficient pentru a se potrivi cu tema? Mă gândesc că lipsa posibilității de a folosi „Studenții voștri credincioși”, pentru o formă de plural (sau, eventual, „Al dumneavoastră credincios” sau „Cu adevărat al dumneavoastră”, pentru o versiune ambiguă) ar face ca enumerarea mai multor autori să pară ciudată și nenaturală (iar aspectul de scrisoare naturală scrisă de un om este una dintre paradigmele de bază ale designului).

  3. Dacă s-a luat în considerare crearea unei metodologii Java Docs, ce alte caracteristici ar trebui incluse? În primul rând, o dată pare ceva obișnuit. Includerea unei forme de comentariu cu data în partea de sus a scrisorii ar arăta probabil natural și nu ar sfida paradigma de proiectare.

Deoarece limbajul este nou, necunoscut pentru majoritatea și, sincer, destul de prostesc, iată câteva resurse de luat în considerare:

Original Release Announcement (Anunț de lansare)

Urmările din octombrie

Wiki

1 răspunsuri
Bart van Ingen Schenau

Care este cerința unei astfel de documentații interne bazate pe comentarii? Există ceva în acest tip special de sintaxă care ar putea cauza probleme?

Cerința de bază este ca analizatorul de documentație să știe ce înseamnă acea bucată de text de program. Acest lucru este independent de ceea ce ar face un compilator cu el.
În acest caz, ajută faptul că gramatica specifică acest lucru ca fiind un student name.

Este cuvântul cheie suficient pentru a se potrivi cu tema? Mă gândesc că lipsa posibilității de a folosi „Studenții dumneavoastră credincioși”, pentru o formă de plural (sau, eventual, „Al dumneavoastră credincios” sau „Cu adevărat”, pentru o versiune ambiguă) ar face ca enumerarea mai multor autori să pară ciudată și nefirească (iar aspectul unei scrisori naturale scrise de un om este una dintre paradigmele de proiectare de bază).

Dacă documentația trebuie să poată face distincția între un autor și mai mulți autori, atunci doar cuvântul cheie actual nu este suficient. Analizatorul de documentație ar trebui să deducă prezența mai multor autori într-un mod diferit (de exemplu, prin utilizarea virgulelor sau a cuvântului „și”).

Comentarii

  • Recomandările de modificare a limbajului sunt deschise pentru discuții, deoarece limbajul este nou și se află în proces de rafinare, din câte am înțeles. Astfel, dacă puteți face ca ceva să funcționeze prin schimbarea acestuia, poate fi rezonabil. Nu ezitați să dezvoltați acest lucru dacă vă ajută să vă susțineți punctul de vedere. –  > Por Southpaw Hare.