nästa upp förra
Nästa: Modulkommentar Upp: Programkommentar Förra: Form

Innehåll

Varje program beskrivs med hjälp av dessa standardrubriker (och deras stycken). Om du tycker att du inte kan få fram det du vill ha sagt m.h.a dessa rubriker beror det förmodligen på att du tänker på ett annat dokument (t.ex. en användarmanual eller en modellbeskrivning e.d.)

NAME
Vad programmet heter, strängen " - ", och på en rad, vad det gör. Enradsbeskrivningen (efter " - ") ska börja med orden "a program", stora eller små bokstäver spelar ingen roll.

Om kommentaren är en samlingskommentar för flera program, så kan programnamnen spänna över flera rader, men beskrivningen ska fortarande få plats på en rad. Det är då ofta vettigt att låta enradsbeskrivningen börja på en egen rad, med strängen " - " följt av ordet "programs" (stora eller små bokstäver spelar ingen roll).

SYNOPSIS
Talar om hur kommandoradssyntaxen för att starta programmet ser ut, exakt. Valbara delar av syntaxen anges med '[' och ']'. Plural anges ofta med ett plural-s (Ex: files). Upprepning anges ofta med tre punkter (...).

DESCRIPTION
Vad programmet gör, (motsvarar en funktionskommentar). Här beskrivs dessutom vilka infiler det läser ifrån (t.ex. standard input), vilka utfiler det skriver på (t.ex. standard output), indataformat, utdataformat, övrig viktig information som behövs för att användaren skall förstå hur programmet beter sig (bruksmodellen).

OBS! Att programmet läser från stdin innebär att det är fel att skriva att det läser från tangentbordet. Att programmet skriver på stdout innebär att det är fel att skriva att programmet skriver på skärmen.

Om man refererar till böcker här, så ha med följande information: Titel, författare, förlag, upplaga, isbn, plus kapitelhänvisning, sidor och annat som är viktigt.

Väljare eller flaggor förklaras inte i denna del, utan i options-delen. Om flödet i beskrivningen blir bättre, kan man dock hänvisa till de väljare och flaggor man behöver för att förklara något.

OPTIONS
Förklaring av vad väljarna/flaggorna betyder.

EXAMPLES
Lagom avancerade exempel. Det är ofta bra med flera exempel som visar olika typfall och både enkla och avancerade användningsfall. Gödsla dock inte med exempel som inte tillför något nytt. Det är alltid en balansgång att avgöra när det är nog med exempel. Väljare som är valfria (inte behöver anges) brukar inte finnas med i exemplen, om de inte är extra knepiga på nåt sätt. För interaktivta program kan det vara bra att visa exempel på interaktionen med programmet.

ENVIRONMENT
Environment-variabler som programmet använder sig av, samt vilka värden dessa får ha. Environment-variabler används ofta för att få ändrings- bara defaultvärden på väljarna. Om en variabel har ett visst värde och användaren inte har angett något annat värde (t.ex. via en väljare) gäller det värde som variabeln har.

FILES
Datafiler som programmet använder sig av. Med detta menas inte c-koden eller header-filerna. Det som avses är de datafiler programmet läser, skriver eller på annat sätt använder sig av.

SEE ALSO
Viktiga relaterade kommandon/program, som bör nänmas.

DIAGNOSTICS
Vilka exitkoder som kan uppträda, när de uppträder och vad de betyder. Man kan antingen sortera på exitkod, och tala om vilka felorsaker som ger upphov till den exitkoden, eller sortera på felorsaker och tala om vilka exitkoder det ger upphov till.

NOTES
Övrig viktig info. Här dokumenteras t.ex. kända fel och brister; samt övrig information som inte hör hemma någon annanstans.

VERSION
Vilken version av programmet det är. Eventuellt kan man tänka sig att ha en versionshanteringsmarkör här, för att automatiskt få rätt version. Detta är dock beroende bl.a. på om versionshanteringen har den typ av markör man behöver, ofta kommer alldeles för mycket information med för de behov man har under denna rubrik.

AUTHOR
Namn på den/de som gjort programmet. Ibland även e-postadressen.

Programkommentar

/* NAME
 *   dosend  -  a program for sending files to other sites
 * 
 * SYNOPSIS
 *   dosend [-arv] [-s site ...] files
 *
 * DESCRIPTION
 *   Dosend sends the given files to the given site. The files will
 *   be placed on /usr/spool/uucppublic on the receiving machine.
 *   Dosend uses the UUCP-package for transmitting the files.
 *
 * OPTIONS
 *   -a         All, send to all uucp-sites this machine knows.
 *   -r         Do not send the files. Just queue them.
 *   -v         Verbose, echo what's going on to stdout.
 *   -s site    Site to send to, repeat -s site if more than one site.
 *   
 * EXAMPLES
 *   dosend -s graff -s dvork  program.c program.h program.doc
 *
 * FILES
 *   /usr/lib/uucp/Systems      -  Information about known sites.
 *
 * SEE ALSO
 *   uucp(1), ftp(1), rcp(1)
 *
 * NOTES
 *   No notification is given as to wether the files ever reached the
 *   receiving machine.
 *
 *   If the files aren't readable by dosend, it will silently exit.
 *   This will be corrected eventually.
 *
 *   This program doesn't work with version 2 UUCP.
 *
 * AUTHOR
 *   Pio Mega, pm@gastroknemius.se
 *
 */


nästa upp förra
Nästa: Modulkommentar Upp: Programkommentar Förra: Form

Jonas Mölsä
Sat Sep 13 13:46:34 MET DST 1997