17 "html|h=s" => \$SOURCE_DIR,
18 "target|t=s" => \$TARGET_DIR,
19 "warnings|W" => \$WARNINGS,
22 pod2usage(0) if $HELP;
32 my $stylesheet = load_stylesheet($SOURCE_DIR);
33 load_templates($SOURCE_DIR, \%templates);
34 process_source_files(\%docs);
35 merge(\%docs, \%templates, \$stylesheet);
39 # Load CSS stylesheet.
43 my $file_path = "$dir_path/api-style.css";
44 open (my $file, '<', $file_path) or die "Could not open $file_path";
46 my $contents = <$file>;
52 # Load HTML templates.
55 my ($dir_path, $templates) = @_;
56 opendir (my $dir, "$dir_path/sources/") or die "Could not open $dir_path";
57 while (my $file_name = readdir ($dir)) {
58 next if $file_name !~ /mono-api-.*\.html$/;
59 open (my $file, "$dir_path/sources/$file_name") or die "Could not open $file_name";
64 if (/name="api:(.*?)"/) {
65 s/.*name="api:(\w+?)".*/$1/;
70 $templates->{$file_name}->{contents} = $contents;
71 $templates->{$file_name}->{api} = \@api;
77 # Extract documentation from all source files.
79 sub process_source_files {
81 for my $file_path (@ARGV) {
82 process_source_file($file_path, $docs);
87 # Extract documentation from a single source file.
89 sub process_source_file {
90 my ($file_path, $docs) = @_;
91 open (my $file, '<', $file_path) or die "Could not open $file_path";
93 next if (!/\/\*\* *\n/);
94 process_function($file, $file_path, $docs);
100 # Extract documentation from a single function.
102 sub process_function {
104 my ($file, $file_path, $docs) = @_;
106 my $PARAMETER_SECTION = 0;
107 my $BODY_SECTION = 1;
108 my $RETURN_SECTION = 2;
109 my $section = $PARAMETER_SECTION;
119 # Ignore irrelevant functions, and those with the wrong doc format.
120 return if $name !~ /^mono_\w+$/;
130 # We've reached the last line in the documentation block.
133 # Grab function prototype.
139 # Clean up prototype.
142 # Strip braces and trailing whitespace.
145 # Turn "Type * xxx" into "Type* xxx"
150 # Process formatting within sections.
151 for my $parameter (@parameters) {
152 process_formatting(\$parameter->{description}, $file_path, $.);
154 process_formatting(\$returns, $file_path, $.);
155 process_formatting(\$body, $file_path, $.);
158 if (exists($docs->{body}->{$name})) {
159 my $origin = $docs->{origin}->{$name};
162 "$file_path:$.: Redundant documentation for $name\n",
163 "$origin->{file}:$origin->{line}: Previously defined here\n";
166 $docs->{origin}->{$name} = { file => $file_path, line => $. };
167 $docs->{body}->{$name} = $body;
168 $docs->{parameters}->{$name} = \@parameters;
169 $docs->{deprecated}->{$name} = $deprecated if defined $deprecated;
170 $docs->{return}->{$name} = $returns;
171 $docs->{prototype}->{$name} = $prototype;
176 # Strip newlines and asterisk prefix.
180 # Replace blank lines with paragraph breaks.
181 $_ = '<p>' if /^\s*$/;
183 if ($section == $PARAMETER_SECTION) {
184 if (/\s*\\param +(\w+)(.*)/) {
185 # print "$file_path:$.: warning: Got parameter $1\n";
186 push @parameters, { name => $1, description => $2 };
187 } elsif (/\s*\\deprecated(.*)/) {
188 # print "$file_path:$.: warning: Got deprecated annotation\n";
190 } elsif (/\s*(\w+):(.*)/) {
191 if ($1 eq 'deprecated') {
192 warn "$file_path:$.: Old-style monodoc notation 'deprecated:' used\n"
196 warn "$file_path:$.: Old-style monodoc notation 'param:' used\n"
198 push @parameters, { name => $1, description => $2 };
202 $section = $BODY_SECTION;
205 } elsif ($section == $BODY_SECTION) {
206 if (s/(Returns?:\s*|\\returns?\s*)//) {
208 $section = $RETURN_SECTION;
212 } elsif ($section == $RETURN_SECTION) {
213 $returns .= "\n\t$_";
215 die "Invalid section $section\n";
221 # Substitute formatting within documentation text.
223 sub process_formatting {
224 my ($content, $file_path, $current_line) = @_;
228 s{NULL}{<code>NULL</code>}g;
229 s{TRUE}{<code>TRUE</code>}g;
230 s{FALSE}{<code>FALSE</code>}g;
233 warn "$file_path:$current_line: Old-style monodoc notation '\@param' used\n"
234 if s{@(\w+)}{<i>$1</i>}g && $WARNINGS;
235 s{\\p +(\w+)}{<i>$1</i>}g;
238 warn "$file_path:$current_line: Old-style monodoc notation '#code' used\n"
239 if s{#(\w+)}{<code>$1</code>}g && $WARNINGS;
240 warn "$file_path:$current_line: Old-style monodoc notation '`code`' used\n"
241 if s{\`((?!api:)[:.\w\*]+)\`}{<code>$1</code>}g && $WARNINGS;
242 s{\\c +([\w\.]+)}{<code>$1</code>}g;
248 # Merge templates with stylesheet and documentation extracted from sources.
251 my ($docs, $templates, $stylesheet) = @_;
253 for my $name (keys %$templates) {
254 open (my $output_file, '>', "$TARGET_DIR/html/$name")
255 or die "Could not create $TARGET_DIR/html/$name";
256 print "Merging: $name\n";
257 print $output_file <<EOF;
258 <?xml version="1.0" encoding="utf-8"?>
259 <html xmlns="http://www.w3.org/1999/xhtml">
262 <style type="text/css">
267 <div class="mapi-docs">
269 my @a = split (/\n/, $templates->{$name}->{contents});
271 my $strikeextra = '';
273 for (my $ai = 0; $ai < $#a; $ai++) {
275 if (my ($api, $caption) = ($line =~ /<h4><a name=\"api:(\w+)\">(\w+)<\/a><\/h4>/)) {
276 if ($api_shown == 1) {
277 print $output_file "</div> <!-- class=mapi -->\n\n";
278 if ($docs->{deprecated}->{$api}) {
279 $strike = "mapi-strike";
280 $strikeextra = "</div><br><div class='mapi-deprecated'><b>Deprecated:</b> " . $docs->{deprecated}->{$api};
287 my $proto = $docs->{prototype}->{$api} // $api;
289 print $output_file <<EOF;
290 <a name="api:$api"></a>
292 <div class="mapi-entry $strike"><code>$api$strikeextra</code></div>
293 <div class="mapi-height-container">
294 <div class="mapi-ptr-container"></div>
295 <div class="mapi-description">
296 <div class="mapi-ptr"></div>
298 <div class="mapi-declaration mapi-section">Syntax</div>
299 <div class="mapi-prototype">$proto</div>
302 if (exists ($docs->{parameters}->{$api})) {
303 my $ppars = $docs->{parameters}->{$api};
306 " <div class=\"mapi-section\">Parameters</div>\n",
307 " <table class=\"mapi-parameters\"><tbody>",
308 render_parameters($ppars),
313 opt_print ($output_file, "Return value", $docs->{return}->{$api});
314 opt_print ($output_file, "Description", $docs->{body}->{$api});
315 print $output_file " </div><!--mapi-description-->\n </div><!--height container-->\n";
317 if ($line =~ /\@API_IDX\@/) {
318 my $apis_toc = create_toc ($docs, $templates->{$name}->{api});
319 $line =~ s/\@API_IDX\@/$apis_toc/;
321 if ($line =~ /^<h4/) {
322 print $output_file "</div>\n";
327 print $output_file "$line\n";
335 system ("$ENV{runtimedir}/mono-wrapper convert.exe $TARGET_DIR/html/$name $TARGET_DIR/html/x-$name");
337 # Clean up the mess that AgilityPack makes (it CDATAs our CSS).
338 open (my $hack_input, '<', "$TARGET_DIR/html/x-$name")
339 or die "Could not open $TARGET_DIR/html/x-$name";
340 open (my $hack_output, '>', "$TARGET_DIR/deploy/$name")
341 or die "Could not open output";
345 while (<$hack_input>) {
346 print $hack_output $last if ($doprint);
348 s/^\/\/<!\[CDATA\[//;
351 # Remove the junk <span> wrapper generated by AgilityPack.
356 # Replace the CSS in the XHTML output with the original CSS.
357 print $hack_output $_;
358 print $hack_output $$stylesheet;
359 while (<$hack_input>) {
360 last if (/<\/style>/);
366 if (!($last =~ /span/)) {
367 print $hack_output $last;
369 # system ("cp.exe $TARGET_DIR/html/$name $TARGET_DIR/deploy/$name");
374 my ($docs, $apis_listed) = @_;
377 my ($ret, $xname, $args);
380 # Try to align things; compute type size, method size, and arguments.
381 foreach my $line (split /\n/, $apis_listed) {
382 if (exists ($docs->{prototype}->{$line})) {
383 my $p = $docs->{prototype}->{$line};
384 if (my ($ret, $xname, $args) = ($p =~ /(.*)\n(\w+)[ \t](.*)/)) {
385 my $tl = length ($ret);
386 my $pl = length ($xname);
387 $type_size = $tl if ($tl > $type_size);
388 $name_size = $pl if ($pl > $name_size);
396 foreach my $line (split /\n/, $apis_listed) {
398 if (exists($docs->{prototype}->{$line})) {
399 my $p = $docs->{prototype}->{$line};
400 if (my ($ret, $xname, $args) = ($p =~ /(.*)\n(\w+)[ \t](.*)/)) {
401 $xname = $line if $xname eq "";
402 my $rspace = " " x ($type_size - length ($ret));
403 my $nspace = " " x ($name_size - length ($xname));
404 $args = wrap ($args, length ($ret . $rspace . $xname . $nspace), 60);
405 $apis_toc .= "$ret$rspace<a href=\"\#api:$line\">$xname</a>$nspace$args\n";
413 my ($args, $size, $limit) = @_;
416 # return $args if ((length (args) + size) < $limit);
418 my $remain = $limit - $size;
419 my @sa = split /,/, $args;
421 foreach my $arg (@sa) {
424 $linelen += length ($sret);
426 if ($linelen + length ($arg) < $limit) {
427 $sret .= "FITS" . $arg . ", ";
429 my $newline = " " x ($size) . $arg . ", ";
430 my $linelen = length ($newline);
431 $sret .= "\n" . $newline;
440 # Print a section if non-empty.
443 my ($output, $caption, $opttext) = @_;
444 if (defined($opttext) && $opttext ne '' && $opttext !~ /^[ \t]+$/) {
446 " <div class=\"mapi-section\">$caption</div>\n",
447 " <div>$opttext</div>\n";
452 # Render parameter information as table.
454 sub render_parameters {
455 my ($parameters) = @_;
457 for my $parameter (@$parameters) {
458 $result .= "<tr><td><i>$parameter->{name}</i></td><td>$parameter->{description}</td></tr>";
467 exdoc - Compiles API docs from Mono sources and HTML templates.
471 exdoc [OPTIONS] [FILE...]
479 Print this help message.
481 =item B<--html> I<DIR>, B<-h> I<DIR>
483 Use I<DIR> as the input path for HTML sources.
485 =item B<--target> I<DIR>, B<-t> I<DIR>
487 Use I<DIR> as the target path for output.
489 =item B<--warnings>, B<-W>
491 Enable warnings about documentation errors.
497 Reads HTML templates and C sources, extracting documentation from the sources and splicing it into the templates.