User login

Languages

Sandcastle dokumentu ģenerators

Iespējams, ka kādam var noderēt mana pieredze ar Sandcastle dokumentu ģeneratoru

Iespējas, plusi un mīnusi

Plusi: 

  • bezmaksas
  • plaša funkcionalitāte
    • izvads - HTML un CHM (help failu) formātā
    • dokumentācijas avoti tiek ģenerēta uz
      • DLL un komentāru XML'i
      • ir iespējams pievienot arī manuāli rakstītus topikus
    • MAML atbalsts gan koda komentāros, gan manuāli pievienotajās tēmās (tas pats par sevi dod iespējas gan dažādi formatēt tekstu, gan iekļaut bildes vai saites uz citām nodaļām/klasēm/u.c)
    • var filtrēt, kas tiks ģenerēts laukā dokumentā
      • namespace's, kas tiks izģenerēti laukā dokumentā
      • klases
      • kāda veida informācija (konstruktori, metodes, atribūti, delegates, u.c.)
    • iespēja pievienot spraudņus (t.sk., uzrakstīt pašam savus). Tie, kas man ir noderējuši
      • dokumentācijas ģenerēšana priekš XSD shēmām
      • koda piemēru iekļaušana ģenerētajā dokumentācijā (tas notiek tā, ka kodā tiek definēts reģions, un example tagā - atsauce uz šo reģionu. Strādā arī priekš XSD)
    • nesaku, ka es visas iespējas tur esmu izpētījis. Man ir tieši pretēja sajūta. 
  • samērā laba dokumentācija
  • atvērts pirmkods, t.i., tīri teorētiski pastāv iespēja arī kaut ko pielabot (līdz šim atļāvos šo iespēju neizmantot).

Mīnusi:

  • totāli platform-atkarīgs (uz Microsoft un priekš Microsoft)
  • neģenerē webservisu dokumentāciju
  • prasa zināmu mācīšanās laiku
    • lai arī kopumā diezgan stabils, tomēr ir nācies uzrauties uz kļūdām, kuru risināšana paņem savu laiku. Parasti atrisinājums nāca, papētot projekta failu, kas īstenībā ir XML formātā. 
    • MAML, lai arī ļauj forši formatēt tekstu, tomēr ir sintakse, kas ir jāiemācās. Arī, ja MAML tiek lietots pārmērīgi, tad paši komentāri kļūst grūti saprotami (teiksim, tabulas). 
  • Ģeneratoram ir arī Visual Studio spraudnis, kas ļauj strādāt ar Sandcastle projektu caur Visual Studio. Es pats noteikti nerekomendēju šo iespēju izmantot, jo tas spraudnis čakarē projekta failu (vismaz man pēc tam nācās ilgi meklēt, kā projekta failu atkal padarīt funkcionējošu).
  • namespaces izvada ar pilnu nosaukumu visos hierarhijas līmeņos. 

 

Kāpēc es to izvēlējos, jeb XML shēmu dokumentēšana

Es pie Sandcastle nonācu brīdī, kad sapratu, ka gribu ģenerēt dokumentāciju XSD shēmām, t.i., nevis aprakstīt XMLu Word dokumentā, bet XML aprakstīt ar XSD palīdzību, kas 

  • ir daudz precīzāk, nekā vārdisks apraksts
  • ļauj validēt XML struktūru 

Šinī kontekstā radās arī vēlme komentēt struktūru pašos XSD failos (nevis aprakstīt atsevišķi), un dokumentāciju ģenerēt. Pretējā gadījumā mēs nonāktu pie liela daudzuma grūti uzturamas Word vai Excel dokumentācijas. 

Jā, un vēl bija vēlme par atrasto dokumentu ģeneratoru nemaksāt :)

Nebija viegli. Es atradu vairākus komerciālus rīkus (diemžēl, neesmu nekur pierakstījis, ko tieši), kas principā ļāva ģenerēt vairāk vai mazāk labu dokumentāciju (bet nebija tā, ka aizrāvās elpa), bet ar bezmaksas rīkiem bija švaki. Viens (un sākumā vienīgais) no variantiem bija x3sp, bet man īsti nepatika ne uzģenerētais rezultāts (milzonīga XHTML lapa), ne arī tas, ka dokumentācija tiek iegūta XSLT transformācijas rezultātā (varu nebaidoties atkārtot - manuprāt, XSLT nav ērts!) Tad googlojot atklāju, ka Sandcastle ir arī XML Schema Documenter spraudnis, un sajutos glābts. Laika gaitā, sastopoties arī ar bugiem un ierobežojumiem, sajūsma samazinājās, bet vēl arvien uzskatu, ka šis ir labs rīks. 

 

Komentāri

Pievienojiet komentāru

Plain text

  • HTML birkas nav atļautas
  • Interneta lapu un e-pastu adreses automātiski tiek pārveidotas par saitēm.
  • Automātiska rindu un rindkopu veidošana
  • Each email address will be obfuscated in a human readable fashion or, if JavaScript is enabled, replaced with a spam resistent clickable link. Email addresses will get the default web form unless specified. If replacement text (a persons name) is required a webform is also required. Separate each part with the "|" pipe symbol. Replace spaces in names with "_".
Image CAPTCHA
Ievadiet attēlā redzamos ciparus
Error | Kaspara Omula mājas lapa
Enter your Kaspara Omula mājas lapa username.
Enter the password that accompanies your username.

Kaspara Omula mājas lapa

Error

The website encountered an unexpected error. Please try again later.