From: Michal Vaner Date: Sat, 26 Jul 2008 14:28:30 +0000 (+0200) Subject: Created documentation system. X-Git-Tag: holmes-import~356 X-Git-Url: http://mj.ucw.cz/gitweb/?a=commitdiff_plain;h=91972e1a8200da60d621b5341fc2e672a6d9f77b;p=libucw.git Created documentation system. `make docs' compiles documentation. It uses asciidoc and is enriched by taking data directly from source code. Some tests are done with ucw/doc/fastbuf.txt and ucw/fastbuf.h. Created documentation is saved into the obj dir. --- diff --git a/build/Makebottom b/build/Makebottom index 92bc47ea..f53b1f79 100644 --- a/build/Makebottom +++ b/build/Makebottom @@ -16,6 +16,7 @@ programs: $(PROGS) datafiles: $(DATAFILES) tests: $(TESTS) configs: $(addprefix run/$(CONFIG_DIR)/,$(CONFIGS)) +docs: runtree $(DOCS) tags: etags `find . -name "*.[ch]"` @@ -191,6 +192,15 @@ $(DATAFILES): $(o)/%: $(s)/% $(Q)cp $^ $@ $(Q)$(call symlink,$@,run/$(DATADIR)) +# Rules for documentation +$(o)/%.html: $(o)/%.txt + $(M)"AD $< -> $@" + $(Q)asciidoc $< + +$(o)/%.txt: $(s)/%.txt + $(M)"ED $< -> $@" + $(Q)$(s)/build/extract-doc.pl $< $@ $(o)/depend.new $(s) + # Default installation target default-install: diff --git a/build/Maketop b/build/Maketop index 5981decf..23d1510a 100644 --- a/build/Maketop +++ b/build/Maketop @@ -72,6 +72,9 @@ distclean:: clean testclean:: rm -f `find obj -name "*.test"` +docclean:: + rm -f $(DOCS) $(patsubst %.html,%.txt,$(DOCS)) + # Extra default rules (appended to by submakefiles) extras:: diff --git a/build/extract-doc.pl b/build/extract-doc.pl new file mode 100755 index 00000000..5f5280db --- /dev/null +++ b/build/extract-doc.pl @@ -0,0 +1,91 @@ +#!/usr/bin/perl +use strict; +use warnings; + +my( $inname, $outname, $depname, $basedir ) = @ARGV; +if( defined $inname ) { + open IN, $inname or die "Could not read $inname ($!)\n"; +} else { + open IN, "<&STDIN" or die "Could not read stdin ($!)\n"; +} +if( defined $outname ) { + open OUT, ">$outname" or die "Could not write $outname ($!)\n"; +} else { + open OUT, ">&STDOUT" or die "Could not write to stdout ($!)\n"; +} +my $hasdep; +if( defined $depname ) { + open DEP, ">>$depname" or die "Could not write $depname ($!)\n"; + $hasdep = 1; +} + +print DEP "$outname:" if( $hasdep ); + +sub process( $ ) { + my $file = shift; + open FILE, $file or die "Could nod read $file ($!)\n"; + my $line; + my $active; + my $verbatim; + my $buff; + my $head; + while( defined( $line = ) ) { + chomp $line; + if( $verbatim ) { + if( $line =~ /\*\// ) { + $verbatim = 0; + } else { + $line =~ s/^\s*\* ?//; + print OUT "$line\n"; + } + } elsif( $active ) { + if( $line =~ /END\*\// ) { + print OUT "$buff\n"; + } elsif( $line =~ /\*\// ) { + $active = 0; + } else { + $line =~ s/^\s*\* ?//; + $line =~ s/^\s*$/+/; + $buff .= "$line\n"; + } + } else { + if( ( $line =~ /\S/ ) && ( defined $buff ) ) { + chomp $line; + $line =~ s/^\s*//; + $line =~ s/\/\/.*//; + $head .= "\n$line"; + if( $head =~ /;/ ) { + $head =~ s/\/\*.*?\*\///gs; + $head =~ s/\s+/ /g; + $head =~ s/;.*/;/; + print OUT "- + +++$head+++ +\n+\n$buff\n"; + $head = undef; + $buff = undef; + } + } elsif( $line =~ /\/\*VERBATIM/ ) { + $verbatim = 1; + } elsif( $line =~ /\/\*DOC/ ) { + $active = 1; + } + } + } + close FILE; +} + +my $line; +while( defined( $line = ) ) { + chomp $line; + if( my( $fname ) = ( $line =~ /^!!\s*(.*\S)/ ) ) { + $fname = "$basedir/$fname" if( ( $fname !~ /^\// ) && defined $basedir ); + process( $fname ); + print DEP " $fname" if( $hasdep ); + } else { + print OUT "$line\n"; + } +} + +print DEP "\n" if( $hasdep ); + +close IN; +close OUT; +close DEP; diff --git a/ucw/Makefile b/ucw/Makefile index bd513a55..5d2ce0c2 100644 --- a/ucw/Makefile +++ b/ucw/Makefile @@ -68,6 +68,7 @@ include $(s)/ucw/getopt/Makefile endif include $(s)/ucw/sorter/Makefile +include $(s)/ucw/doc/Makefile LIBUCW_MOD_PATHS=$(addprefix $(o)/ucw/,$(LIBUCW_MODS)) diff --git a/ucw/doc/Makefile b/ucw/doc/Makefile new file mode 100644 index 00000000..69146fd0 --- /dev/null +++ b/ucw/doc/Makefile @@ -0,0 +1,5 @@ +# Makefile for the UCW GetOpt Library (c) 2007 Pavel Charvat + +DIRS+=ucw/doc + +DOCS+=$(addprefix $(o)/ucw/doc/,fastbuf.html) diff --git a/ucw/doc/fastbuf.txt b/ucw/doc/fastbuf.txt new file mode 100644 index 00000000..df803a08 --- /dev/null +++ b/ucw/doc/fastbuf.txt @@ -0,0 +1,12 @@ +Fastbufs +======== + +Fastbufs are stream and file abstractions. They work with normal +files, network sockets, memory buffers or just any file descriptor. It +should be easy to implement other types by providing functions to +refill and read the buffer. + +Apart from abstraction, they are very fast. + +The main iclude file is +ucw/fastbuf.h+: + +!!ucw/fastbuf.h diff --git a/ucw/fastbuf.h b/ucw/fastbuf.h index 07e893f1..4fb02bb6 100644 --- a/ucw/fastbuf.h +++ b/ucw/fastbuf.h @@ -94,8 +94,18 @@ struct cf_section; extern struct cf_section fbpar_cf; extern struct fb_params fbpar_def; +/*DOC + * Opens a file. + */ struct fastbuf *bopen_file(const char *name, int mode, struct fb_params *params); /* Use params==NULL for defaults */ -struct fastbuf *bopen_file_try(const char *name, int mode, struct fb_params *params); +/*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 + * 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)