• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
PHP Documentation APIs on the fly
 

PHP Documentation APIs on the fly

on

  • 733 views

All’interno del ciclo di vita di un progetto software reputo importante la percentuale di tempo dedicata a redigere la documentazione di progetto, a volte, anzi direi molto di frequente la ...

All’interno del ciclo di vita di un progetto software reputo importante la percentuale di tempo dedicata a redigere la documentazione di progetto, a volte, anzi direi molto di frequente la percentuale di tempo dedicata a quest’attività, è intorno allo zero.

Statistics

Views

Total Views
733
Views on SlideShare
733
Embed Views
0

Actions

Likes
0
Downloads
0
Comments
0

0 Embeds 0

No embeds

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

CC Attribution-NonCommercial-ShareAlike LicenseCC Attribution-NonCommercial-ShareAlike LicenseCC Attribution-NonCommercial-ShareAlike License

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

    PHP Documentation APIs on the fly PHP Documentation APIs on the fly Document Transcript

    • Antonio  Musarra's  Blog   The  ideal  solution  for  a  problem   Blog:  http://musarra.wordpress.com   Mail:  antonio.musarra@gmail.com     PHP  Documentation  APIs  on  the  fly   All’interno   del   ciclo   di   vita   di   un   progetto   software   reputo   importante   la   percentuale   di   tempo   dedicata   a   redigere   la   documentazione   di   progetto,   a   volte,   anzi  direi  molto  di  frequente  la  percentuale  di  tempo  dedicata  a  quest’attività,  è   intorno  allo  zero.   La   documentazione   che   accompagna   un   progetto   software   è   di   vario   tipo,   per   esperienza   personale   ritengo   che   una   buona   documentazione   delle   API   sia   una   cosa   gradita   soprattutto   ai   “posteri”   che   in   futuro   dovranno   utilizzare   o   estendere  il  progetto  software.     Non  ho  nessuna  remora  nell’affermare  che  la  documentazione  delle  API  si   scrive   da   sola,   nello   stesso   istante   dedicato   alla   scrittura   del   codice   sorgente.   Redigere   la   documentazione   mentre   si   scrive   il   codice,   è   molto   semplice,   ciò   è   reso  possibile  grazie  a  particolari  annotazioni  e  tools1.   Nel   corso   di   questo   breve   articolo   vedremo   come   generare   on   the   fly   la   documentazione  delle  API  di  un  progetto  scritto  in  PHP2;  potremmo  per  esempio   prendere   in   considerazione   il   progetto   Open   Source   Wordpress3  e   di   questo   generare  la  documentazione  delle  API4.  Assumiamo  che:     • L’ambiente  di  sviluppo  sia  Eclipse  PDT  Helios5;   • Il  progetto  Wordpress  sia  presente  nel  proprio  workspace  Eclipse;     • Sul  sistema  sia  installato  e  correttamente  configurato  il  tool  PHPDoc.     Il   progetto   Wordpress   può   essere   creato   sul   proprio   workspace   Eclipse   direttamente  dal  repository  SVN  pubblico  di  wordpress.org.  Tutte  le  informazioni   necessarie  sono  disponibili  all’indirizzo  http://wordpress.org/download/svn/  .   Il  “trucco  dell’on  the  fly”  è  abbastanza  semplice,  basta  configurare  su  Eclipse   PDT   Helios   un   cosiddetto   External   Tools,   che   nel   nostro   caso   chiamerà   il   tool   PHPDoc   passando   opportuni   parametri.   L’External   Tool   che   andremo   a   creare   prenderà   il   nome   di   Wordpress   API   Docs.   E’   talmente   semplice   la   procedura   di   creazione   dell’External   Tools   che   ho   preferito   utilizzare   delle   illustrazioni   con   opportune   indicazioni.   Nelle   figure   che   seguono,   sono   quindi   illustrati   i   passi   necessari  alla  creazione  del  comando  per  generare  il  documento  delle  API.                                                                                                                     1  Analizzano   il   codice   sorgente   e   generano   la   documentazione   in   vari   formati   di   output   (HTML,   PDF,   DocBook,   etc…).   JavaDoc,  PHPDoc,  Doxygen,  etc…  sono  alcuni  di  questi.   2  PHP   (acronimo   ricorsivo   di   "PHP:   Hypertext   Preprocessor",   preprocessore   d’ipertesti)   è   un   linguaggio   di   scripting   interpretato,   con   licenza   open   source   e   libera   (ma   incompatibile   con   la   GPL),   originariamente   concepito   per   la   programmazione  Web  ovvero  la  realizzazione  di  pagine  web  dinamiche.   3  E’   una   piattaforma   di   "personal   publishing"   e   content   management   system   (CMS),   scritta   in   PHP   e   che   usa   come   database  MySQL.  Creata  da  Matt  Mullenweg,  è  distribuita  con  la  licenza  GNU  General  Public  License.   4  Le   Application   Programming   Interface   API   (Interfaccia   di   Programmazione   di   un'Applicazione),   sono   ogni   insieme   di   procedure  disponibili  al  programmatore,  di  solito  raggruppate  a  formare  un  set  di  strumenti  specifici  per  un  determinato   compito.  È  un  metodo  per  ottenere  un'astrazione,  di  solito  tra  l'hardware  e  il  programmatore,  o  tra  software  a  basso  ed   alto   livello.   Le   API   permettono   di   evitare   ai   programmatori   di   scrivere   tutte   le   funzioni   dal   nulla.   Le   API   stesse   sono   un'astrazione:  il  software  che  fornisce  una  certa  API  è  detto  che  implementa  le  API.   5  L’IDE   Eclipse   dedicato   all’ambiente   di   sviluppo   PHP.   Per   maggiori   informazioni   consultare   il   sito   http://www.eclipse.org/pdt/       11/01/11   1   This  document  is  issued  with  license  Creative  Commons  Attribution-­‐NonCommercial-­‐ShareAlike      
    • Antonio  Musarra's  Blog   The  ideal  solution  for  a  problem   Blog:  http://musarra.wordpress.com   Mail:  antonio.musarra@gmail.com                Figura  1  Menu  di  accesso  alla  funzione  di  creazione  e  configurazione  External  Tools.       Figura  2  Creazione  dell’External  Tools  Wordpress  API  Docs.   Il   box   Arguments   (sezione   numero   quattro)   della   Figura   2   indica   quali   parametri  da  passare  al  comando  phpdoc,  in  particolare,  il  parametro  –d  imposta   il   folder   contenente   il   codice   sorgente   da   cui   generare   la   documentazione   delle   API,   e   il   valore   assegnato   (${folder_prompt})   fa   sì   che   sia   l’utente   a   scegliere   il   folder.     11/01/11   2   This  document  is  issued  with  license  Creative  Commons  Attribution-­‐NonCommercial-­‐ShareAlike      
    • Antonio  Musarra's  Blog   The  ideal  solution  for  a  problem   Blog:  http://musarra.wordpress.com   Mail:  antonio.musarra@gmail.com           Figura  3  External  Tools  Wordpress  API  Docs  aggiunto  alla  lista  dopo  la  creazione.       Figura  4  Wordpress  API  Docs  in  action.               11/01/11   3   This  document  is  issued  with  license  Creative  Commons  Attribution-­‐NonCommercial-­‐ShareAlike      
    • Antonio  Musarra's  Blog   The  ideal  solution  for  a  problem   Blog:  http://musarra.wordpress.com   Mail:  antonio.musarra@gmail.com       Figura  5  TreeView  documentazione  API.       Figura  6  Home  Page  della  documentazione  delle  API.     11/01/11   4   This  document  is  issued  with  license  Creative  Commons  Attribution-­‐NonCommercial-­‐ShareAlike      
    • Antonio  Musarra's  Blog   The  ideal  solution  for  a  problem   Blog:  http://musarra.wordpress.com   Mail:  antonio.musarra@gmail.com           Figura  7  Documentazione  di  dettaglio  su  di  una  classe  parte  delle  API.     11/01/11   5   This  document  is  issued  with  license  Creative  Commons  Attribution-­‐NonCommercial-­‐ShareAlike