generator/generator_docstrings.ml

   1 (* libguestfs
   2  * Copyright (C) 2009-2010 Red Hat Inc.
   3  *
   4  * This program is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation; either version 2 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program; if not, write to the Free Software
  16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  17  *)
  18
  19 (* Please read generator/README first. *)
  20
  21 open Unix
  22 open Printf
  23
  24 open Generator_types
  25 open Generator_utils
  26 open Generator_pr
  27
  28 (* Handling for function flags. *)
  29 let progress_message =
  30   "This long-running command can generate progress notification messages
  31 so that the caller can display a progress bar or indicator.
  32 To receive these messages, the caller must register a progress
  33 event callback.  See L<guestfs(3)/GUESTFS_EVENT_PROGRESS>."
  34
  35 let protocol_limit_warning =
  36   "Because of the message protocol, there is a transfer limit
  37 of somewhere between 2MB and 4MB.  See L<guestfs(3)/PROTOCOL LIMITS>."
  38
  39 let danger_will_robinson =
  40   "B<This command is dangerous.  Without careful use you
  41 can easily destroy all your data>."
  42
  43 let deprecation_notice ?(prefix = "") flags =
  44   try
  45     let alt =
  46       find_map (function DeprecatedBy str -> Some str | _ -> None) flags in
  47     let txt =
  48       sprintf "I<This function is deprecated.>
  49 In new code, use the L</%s%s> call instead.
  50
  51 Deprecated functions will not be removed from the API, but the
  52 fact that they are deprecated indicates that there are problems
  53 with correct use of these functions." prefix alt in
  54     Some txt
  55   with
  56     Not_found -> None
  57
  58 let copyright_years =
  59   let this_year = 1900 + (localtime (time ())).tm_year in
  60   if this_year > 2009 then sprintf "2009-%04d" this_year else "2009"
  61
  62 (* Generate a header block in a number of standard styles. *)
  63 type comment_style =
  64     CStyle | CPlusPlusStyle | HashStyle | OCamlStyle | HaskellStyle
  65   | ErlangStyle
  66 type license = GPLv2plus | LGPLv2plus
  67
  68 let generate_header ?(extra_inputs = []) comment license =
  69   let inputs = "generator/generator_*.ml" :: extra_inputs in
  70   let c = match comment with
  71     | CStyle ->         pr "/* "; " *"
  72     | CPlusPlusStyle -> pr "// "; "//"
  73     | HashStyle ->      pr "# ";  "#"
  74     | OCamlStyle ->     pr "(* "; " *"
  75     | HaskellStyle ->   pr "{- "; "  "
  76     | ErlangStyle ->    pr "%% "; "% " in
  77   pr "libguestfs generated file\n";
  78   pr "%s WARNING: THIS FILE IS GENERATED FROM:\n" c;
  79   List.iter (pr "%s   %s\n" c) inputs;
  80   pr "%s ANY CHANGES YOU MAKE TO THIS FILE WILL BE LOST.\n" c;
  81   pr "%s\n" c;
  82   pr "%s Copyright (C) %s Red Hat Inc.\n" c copyright_years;
  83   pr "%s\n" c;
  84   (match license with
  85    | GPLv2plus ->
  86        pr "%s This program is free software; you can redistribute it and/or modify\n" c;
  87        pr "%s it under the terms of the GNU General Public License as published by\n" c;
  88        pr "%s the Free Software Foundation; either version 2 of the License, or\n" c;
  89        pr "%s (at your option) any later version.\n" c;
  90        pr "%s\n" c;
  91        pr "%s This program is distributed in the hope that it will be useful,\n" c;
  92        pr "%s but WITHOUT ANY WARRANTY; without even the implied warranty of\n" c;
  93        pr "%s MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n" c;
  94        pr "%s GNU General Public License for more details.\n" c;
  95        pr "%s\n" c;
  96        pr "%s You should have received a copy of the GNU General Public License along\n" c;
  97        pr "%s with this program; if not, write to the Free Software Foundation, Inc.,\n" c;
  98        pr "%s 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.\n" c;
  99
 100    | LGPLv2plus ->
 101        pr "%s This library is free software; you can redistribute it and/or\n" c;
 102        pr "%s modify it under the terms of the GNU Lesser General Public\n" c;
 103        pr "%s License as published by the Free Software Foundation; either\n" c;
 104        pr "%s version 2 of the License, or (at your option) any later version.\n" c;
 105        pr "%s\n" c;
 106        pr "%s This library is distributed in the hope that it will be useful,\n" c;
 107        pr "%s but WITHOUT ANY WARRANTY; without even the implied warranty of\n" c;
 108        pr "%s MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU\n" c;
 109        pr "%s Lesser General Public License for more details.\n" c;
 110        pr "%s\n" c;
 111        pr "%s You should have received a copy of the GNU Lesser General Public\n" c;
 112        pr "%s License along with this library; if not, write to the Free Software\n" c;
 113        pr "%s Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA\n" c;
 114   );
 115   (match comment with
 116    | CStyle -> pr " */\n"
 117    | CPlusPlusStyle
 118    | ErlangStyle
 119    | HashStyle -> ()
 120    | OCamlStyle -> pr " *)\n"
 121    | HaskellStyle -> pr "-}\n"
 122   );
 123   pr "\n"