From: Michal Vaner Date: Sun, 27 Jul 2008 11:32:30 +0000 (+0200) Subject: Enhanced documentation system. X-Git-Tag: holmes-import~355 X-Git-Url: http://mj.ucw.cz/gitweb/?a=commitdiff_plain;h=01b1c8a44e698ba72a0e24c6c02a3662c3ba9fa2;p=libucw.git Enhanced documentation system. Comments are now /** * Function comment. **/ void function(void); or void function(void); /** Function comment **/ /*** * Verbatim comment. ***/ or /*** Verbatim comment ***/ @param marks a function parameter. It understands structures (to level 1, nested functions are flattened. Is it needed?). --- diff --git a/build/Makebottom b/build/Makebottom index f53b1f79..471fd356 100644 --- a/build/Makebottom +++ b/build/Makebottom @@ -195,7 +195,7 @@ $(DATAFILES): $(o)/%: $(s)/% # Rules for documentation $(o)/%.html: $(o)/%.txt $(M)"AD $< -> $@" - $(Q)asciidoc $< + $(Q)asciidoc -f $(s)/build/docconfig $< $(o)/%.txt: $(s)/%.txt $(M)"ED $< -> $@" diff --git a/build/docconfig b/build/docconfig new file mode 100644 index 00000000..7326cfc9 --- /dev/null +++ b/build/docconfig @@ -0,0 +1,2 @@ +[replacements] +@(\w+)=\1 diff --git a/build/extract-doc.pl b/build/extract-doc.pl index 5f5280db..dca2e53d 100755 --- a/build/extract-doc.pl +++ b/build/extract-doc.pl @@ -29,6 +29,8 @@ sub process( $ ) { my $verbatim; my $buff; my $head; + my $levelMark = '-'; + my $markDepth; while( defined( $line = ) ) { chomp $line; if( $verbatim ) { @@ -39,9 +41,7 @@ sub process( $ ) { print OUT "$line\n"; } } elsif( $active ) { - if( $line =~ /END\*\// ) { - print OUT "$buff\n"; - } elsif( $line =~ /\*\// ) { + if( $line =~ /\*\// ) { $active = 0; } else { $line =~ s/^\s*\* ?//; @@ -54,17 +54,33 @@ sub process( $ ) { $line =~ s/^\s*//; $line =~ s/\/\/.*//; $head .= "\n$line"; - if( $head =~ /;/ ) { + if( $head =~ /[;{]/ ) { $head =~ s/\/\*.*?\*\///gs; $head =~ s/\s+/ /g; - $head =~ s/;.*/;/; - print OUT "- + +++$head+++ +\n+\n$buff\n"; + $head =~ s/([;{]).*/$1/; + print OUT $levelMark." + +++$head+++ +\n+\n$buff\n"; + if( $head =~ /\{/ ) { + $levelMark = '*' unless( $markDepth ++ ); + } $head = undef; $buff = undef; } - } elsif( $line =~ /\/\*VERBATIM/ ) { + } elsif( my( $head, $comment ) = ( $line =~ /^(.*)\/\*\*(.*)\*\*\// ) ) { + $head =~ s/^\s*//; + $head =~ s/\/\*.*?\*\///gs; + $head =~ s/\s+/ /g; + $head =~ s/([;{]).*/$1/; + $comment =~ s/^\s*//; + $comment =~ s/\s*$//; + print OUT $levelMark." + +++$head+++ +\n+\n$comment\n\n"; + if( $head =~ /\{/ ) { + $levelMark = '*' unless( $markDepth ++ ); + } + } elsif( $line =~ /\}/ && $markDepth ) { + $levelMark = '-' unless( -- $markDepth ); + } elsif( $line =~ /\/\*\*\*/ ) { $verbatim = 1; - } elsif( $line =~ /\/\*DOC/ ) { + } elsif( $line =~ /\/\*\*/ ) { $active = 1; } } diff --git a/ucw/doc/fastbuf.txt b/ucw/doc/fastbuf.txt index df803a08..71e9dc07 100644 --- a/ucw/doc/fastbuf.txt +++ b/ucw/doc/fastbuf.txt @@ -8,5 +8,7 @@ refill and read the buffer. Apart from abstraction, they are very fast. -The main iclude file is +ucw/fastbuf.h+: + +ucw/fastbuf.h +------------- + !!ucw/fastbuf.h diff --git a/ucw/fastbuf.h b/ucw/fastbuf.h index 4fb02bb6..855afa46 100644 --- a/ucw/fastbuf.h +++ b/ucw/fastbuf.h @@ -14,11 +14,11 @@ #include #include -/* - * Generic buffered I/O. You supply hooks to be called for low-level operations - * (swapping of buffers, seeking and closing), we do the rest. +/*** + * Generic buffered I/O. You supply hooks to be called for low-level operations + * (swapping of buffers, seeking and closing), we do the rest. * - * Buffer layout when reading: + * Buffer layout when reading: * * +----------------+---------------------------+ * | read data | free space | @@ -26,11 +26,11 @@ * ^ ^ ^ ^ * buffer bptr bstop bufend * - * After the last character is read, bptr == bstop and buffer refill - * is deferred to the next read attempt. This gives us an easy way - * how to implement bungetc(). + * After the last character is read, +bptr == bstop+ and buffer refill + * is deferred to the next read attempt. This gives us an easy way + * how to implement +bungetc()+. * - * When writing: + * When writing: * * +--------+--------------+--------------------+ * | unused | written data | free space | @@ -38,74 +38,75 @@ * ^ ^ ^ ^ * buffer bstop bptr bufend * - * Dirty tricks: + * Dirty tricks: * * - You can mix reads and writes on the same stream, but you must - * call bflush() in between and remember that the file position + * call +bflush()+ in between and remember that the file position * points after the flushed buffer which is not necessarily the same * as after the data you've read. * - The spout/refill hooks can change not only bptr and bstop, but also - * the location of the buffer; fb-mem.c takes advantage of it. - * - In some cases, the user of the bdirect interface can be allowed to modify + * the location of the buffer; +fb-mem.c+ takes advantage of it. + * - In some cases, the user of the +bdirect+ interface can be allowed to modify * the data in the buffer to avoid unnecessary copying. If the back-end - * allows such modifications, it can set can_overwrite_buffer accordingly: + * allows such modifications, it can set +can_overwrite_buffer+ accordingly: * * 0 if no modification is allowed, * * 1 if the user can modify the buffer on the condition that * the modifications will be undone before calling the next * fastbuf operation * * 2 if the user is allowed to overwrite the data in the buffer - * if bdirect_read_commit_modified() is called afterwards. + * if +bdirect_read_commit_modified()+ is called afterwards. * In this case, the back-end must be prepared for trimming * of the buffer which is done by the commit function. - */ - -struct fastbuf { - byte is_fastbuf[0]; /* Dummy field for checking of type casts */ - byte *bptr, *bstop; /* Access pointers */ - byte *buffer, *bufend; /* Start and end of the buffer */ - char *name; /* File name for error messages */ - ucw_off_t pos; /* Position of bstop in the file */ - int (*refill)(struct fastbuf *); /* Get a buffer with new data */ - void (*spout)(struct fastbuf *); /* Write buffer data to the file */ - int (*seek)(struct fastbuf *, ucw_off_t, int); /* Slow path for bseek(), buffer already flushed; returns success */ - void (*close)(struct fastbuf *); /* Close the stream */ - int (*config)(struct fastbuf *, uns, int); /* Configure the stream */ - int can_overwrite_buffer; /* Can the buffer be altered? (see discussion above) 0=never, 1=temporarily, 2=permanently */ + * + * File content + * ~~~~~~~~~~~~ + ***/ + +struct fastbuf { /** Fastbuf structure **/ + byte is_fastbuf[0]; /** Dummy field for checking of type casts **/ + byte *bptr, *bstop; /** Access pointers **/ + byte *buffer, *bufend; /** Start and end of the buffer **/ + char *name; /** File name for error messages **/ + ucw_off_t pos; /** Position of bstop in the file **/ + int (*refill)(struct fastbuf *); /** Get a buffer with new data **/ + void (*spout)(struct fastbuf *); /** Write buffer data to the file **/ + int (*seek)(struct fastbuf *, ucw_off_t, int); /** Slow path for bseek(), buffer already flushed; returns success **/ + void (*close)(struct fastbuf *); /** Close the stream **/ + int (*config)(struct fastbuf *, uns, int); /** Configure the stream **/ + int can_overwrite_buffer; /** Can the buffer be altered? (see discussion above) 0=never, 1=temporarily, 2=permanently **/ }; /* FastIO on files with several configurable back-ends */ -enum fb_type { /* Which back-end you want to use */ - FB_STD, /* Standard buffered I/O */ - FB_DIRECT, /* Direct I/O bypassing system caches (see fb-direct.c for a description) */ - FB_MMAP /* Memory mapped files */ +enum fb_type { /** Which back-end you want to use **/ + FB_STD, /** Standard buffered I/O **/ + FB_DIRECT, /** Direct I/O bypassing system caches (see +fb-direct.c+ for a description) **/ + FB_MMAP /** Memory mapped files **/ }; -struct fb_params { - enum fb_type type; - uns buffer_size; /* 0 for default size */ - uns keep_back_buf; /* FB_STD: optimize for bi-directional access */ - uns read_ahead; /* FB_DIRECT options */ - uns write_back; - struct asio_queue *asio; +struct fb_params { /** **/ + enum fb_type type; /** **/ + uns buffer_size; /** 0 for default size **/ + uns keep_back_buf; /** FB_STD: optimize for bi-directional access **/ + uns read_ahead; /** FB_DIRECT options **/ + uns write_back; /** **/ + struct asio_queue *asio; /** **/ }; struct cf_section; -extern struct cf_section fbpar_cf; -extern struct fb_params fbpar_def; +extern struct cf_section fbpar_cf; /** Config **/ +extern struct fb_params fbpar_def; /** Default parameters **/ -/*DOC +/** * Opens a file. - */ -struct fastbuf *bopen_file(const char *name, int mode, struct fb_params *params); /* Use params==NULL for defaults */ -/*DOC - * Tries to open a file (does not die, if it isn't sucessful). - */ -struct fastbuf /*BLAXLA*/ *bopen_file_try(const /*BAX*/ char *name, int mode, struct fb_params *params); -/*DOC + * Use +@params = NULL+ for defaults. + **/ +struct fastbuf *bopen_file(const char *name, int mode, struct fb_params *params); +struct fastbuf *bopen_file_try(const char *name, int mode, struct fb_params *params); /** Tries to open a file (does not die, if unsuccessful) **/ +/** * Opens a temporary file. * It is placed with other temp filenames and deleted when closed. - */ + **/ struct fastbuf *bopen_tmp_file(struct fb_params *params); struct fastbuf *bopen_fd_name(int fd, struct fb_params *params, const char *name); static inline struct fastbuf *bopen_fd(int fd, struct fb_params *params)