source: trunk/libdjvu/Template.h @ 426

Last change on this file since 426 was 280, checked in by rbri, 12 years ago

DJVU plugin: djvulibre updated to version 3.5.22

File size: 9.5 KB
Line 
1//C-  -*- C++ -*-
2//C- -------------------------------------------------------------------
3//C- DjVuLibre-3.5
4//C- Copyright (c) 2002  Leon Bottou and Yann Le Cun.
5//C- Copyright (c) 2001  AT&T
6//C-
7//C- This software is subject to, and may be distributed under, the
8//C- GNU General Public License, either Version 2 of the license,
9//C- or (at your option) any later version. The license should have
10//C- accompanied the software or you may obtain a copy of the license
11//C- from the Free Software Foundation at http://www.fsf.org .
12//C-
13//C- This program is distributed in the hope that it will be useful,
14//C- but WITHOUT ANY WARRANTY; without even the implied warranty of
15//C- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16//C- GNU General Public License for more details.
17//C-
18//C- DjVuLibre-3.5 is derived from the DjVu(r) Reference Library from
19//C- Lizardtech Software.  Lizardtech Software has authorized us to
20//C- replace the original DjVu(r) Reference Library notice by the following
21//C- text (see doc/lizard2002.djvu and doc/lizardtech2007.djvu):
22//C-
23//C-  ------------------------------------------------------------------
24//C- | DjVu (r) Reference Library (v. 3.5)
25//C- | Copyright (c) 1999-2001 LizardTech, Inc. All Rights Reserved.
26//C- | The DjVu Reference Library is protected by U.S. Pat. No.
27//C- | 6,058,214 and patents pending.
28//C- |
29//C- | This software is subject to, and may be distributed under, the
30//C- | GNU General Public License, either Version 2 of the license,
31//C- | or (at your option) any later version. The license should have
32//C- | accompanied the software or you may obtain a copy of the license
33//C- | from the Free Software Foundation at http://www.fsf.org .
34//C- |
35//C- | The computer code originally released by LizardTech under this
36//C- | license and unmodified by other parties is deemed "the LIZARDTECH
37//C- | ORIGINAL CODE."  Subject to any third party intellectual property
38//C- | claims, LizardTech grants recipient a worldwide, royalty-free,
39//C- | non-exclusive license to make, use, sell, or otherwise dispose of
40//C- | the LIZARDTECH ORIGINAL CODE or of programs derived from the
41//C- | LIZARDTECH ORIGINAL CODE in compliance with the terms of the GNU
42//C- | General Public License.   This grant only confers the right to
43//C- | infringe patent claims underlying the LIZARDTECH ORIGINAL CODE to
44//C- | the extent such infringement is reasonably necessary to enable
45//C- | recipient to make, have made, practice, sell, or otherwise dispose
46//C- | of the LIZARDTECH ORIGINAL CODE (or portions thereof) and not to
47//C- | any greater extent that may be necessary to utilize further
48//C- | modifications or combinations.
49//C- |
50//C- | The LIZARDTECH ORIGINAL CODE is provided "AS IS" WITHOUT WARRANTY
51//C- | OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
52//C- | TO ANY WARRANTY OF NON-INFRINGEMENT, OR ANY IMPLIED WARRANTY OF
53//C- | MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
54//C- +------------------------------------------------------------------
55//
56// $Id: Template.h,v 1.9 2007/03/25 20:48:34 leonb Exp $
57// $Name: release_3_5_22 $
58
59//T// This is a template for the header files in the
60//T// DjVu reference library. It describes the general
61//T// conventions as well as the documentation.
62//T// Comments prefixed with '//T//' explain the template
63//T// features and should be removed.
64
65#ifndef _TEMPLATE_H_
66#define _TEMPLATE_H_
67#ifdef HAVE_CONFIG_H
68#include "config.h"
69#endif
70#if NEED_GNUG_PRAGMAS
71# pragma interface
72#endif
73
74//T// Always include "DjVuGlobal.h"
75#include "DjVuGlobal.h"
76
77//T// Other include files
78#include <string.h>
79#include "GException.h"
80
81//T// Begin name space
82
83#ifdef HAVE_NAMESPACES
84namespace DJVU {
85# ifdef NOT_DEFINED // Just to fool emacs c++ mode
86}
87#endif
88#endif
89
90/** @name Template.h
91   
92    Files #"Template.h"# and #"Template.cpp"# are not used for anything but
93    the current programming and documentation standards in the DjVu reference
94    library. This doc++ comment briefly describes the abstractions defined in
95    this files.  It must mention all the files involved in implementing this
96    features, as well as references to the main classes \Ref{classname}. 
97
98    This comment may contain additional sections as follows:
99
100    {\bf Algorithmic Remarks} --- Comments about the algorithms, their
101    performance and their limitations.
102
103    {\bf Historical Remarks} --- Comments about the successive revisions of
104    this file and other anecdotical details. This is where we can amuse the
105    reader with funny details.
106
107    {\bf ToDo} --- Things that we have been thinking to do but did not
108    fully implement yet. It should explain how we plan to modify the current
109    code could be modified to implement these things. People who change this
110    code thus should avoid jeopardizing these plans.
111   
112    {\bf Example} --- It would be cool to demonstrate how these functions
113    can be used by providing a small segment of C/C++ code.
114    \begin{verbatim}
115       ExampleClass toto(3,4);
116       toto.draw(mywin);
117    \end{verbatim}
118
119    This main doc++ comment is followed by a few doc++ entries.
120    \begin{itemize}
121    \item the "memo" field contains a single line description of the file.
122    \item the "version" field contains a cvs magic expression.
123    \item the author fields contains a list of authors and email addresses.
124          (the #\\# termination breaks the line.)
125    \end{itemize}
126
127    @memo
128    Template header file
129    @version
130    #$Id: Template.h,v 1.9 2007/03/25 20:48:34 leonb Exp $#
131    @author:
132    L\'eon Bottou <leonb@research.att.com> -- initial implementation \\
133    Andrew Erofeev <eaf@geocities.com> -- implemented EXTERNAL_TEMPLATES */
134//@{
135//T// The magic doc++ comment above opens a doc++ context.
136
137
138
139//T// Now comes the 'interface part' of the file.
140//T// The c++ classes and public functions are defined there.
141//T// Doc++ comments must be inserted for all functions
142//T// intended to be used by other people.
143//T//
144//T// Quite often c++ sucks and it is necessary to have public or external symbols
145//T// that actually are only there for implementation purposes.
146//T// It is good to give a comment but this should not be a doc++ comment
147//T// (see class GPool in GContainer.h).  All other 'public' and 'protected'
148//T// members should have a doc++ comment. There is no need to comment 'private'
149//T// members, although a regular comment can be useful (not a doc++ comment).
150
151
152
153/** One-line class description.
154    Long description. There is no need to repeat the class name in the
155    one-line description. The long description should describe the abstraction
156    and point the user to the main member functions.  An example could be
157    inserted when this is informative and not redundant with the file
158    description.  Templates should document which member functions are
159    required for their type argument. The availability of non availabilty of a
160    copy constructor/copy operator can be specified when appropriate.
161    See the doc++ documentation for available LaTeX constructs.
162*/
163
164class ExampleClass
165{
166public:
167  /** Virtual Destructor. */
168  ~ExampleClass();
169  /** Null Constructor. */
170  ExampleClass();
171  /** Copy Constructor. */
172  ExampleClass(ExampleClass &ref);
173  /** Copy operator. */
174  ExampleClass& operator=(ExampleClass &ref);
175  /** Example of member function. The first sentence of the member
176      function description must be a short single line description.
177      The rest can be more verbose. Excerpts of C or C++ text should
178      be surrounded by dieze characters (as in #win#).  The doc++ #@param#
179      construct should be used when there is a need for additional details
180      about the arguments. In that case all the arguments must be documented
181      with a #@param# directive.
182      @param win drawing window.
183      This window must be created with #CreateWindow# and must be visible when
184      function #draw# is called.
185   */
186  void draw(Window win);
187protected:
188  /** Minimal x-coordinate. */
189  int xmin;
190  /** Maximal x-coordinate. */
191  int xmax;
192private:
193  int whatever;
194  float encode;
195};
196
197
198/** One-line function description.
199    Long description. Public external functions should be documented
200    as classes. Note that a family of public external function can be
201    introduced by a generic entry (see below) */
202
203ExampleClass combine_example_classes(const ExampleClass&, 
204                                     const ExampleClass &b);
205
206
207/** @name Generic entry.
208    Long description. there is sometimes a need to add documentation
209    entries for grouping things which are not connected by the C++
210    syntax (a family of functions, a family of defines, etc...).
211    The description starts with a very short name (introduced with #@name#)
212    followed by a long description.  Because of doc++ limitations,
213    the one-line description must appear after the long description
214    in a #@memo# entry.
215    @memo One-line description
216*/
217
218//T// The following comments should be used when
219//T// the preceding generic entry contains sub-entries
220//@{
221//T// Sub-entries (both DOC++ and C++) should be declared there.
222//@}
223
224
225
226
227
228
229//@}
230//T// The magic doc++ comment above closes the doc++ file context.
231//T// The rest of the file only contains implementation stuff.
232
233// ------------ CLASSEXAMPLE INLINES
234//T// This is where all the inline/template functions should be written
235//T// This part of the file is segmented with comments.
236
237inline void 
238ClassExample::width()
239{
240  return xmax-xmin;
241}
242
243
244
245// ------------ THE END
246//T// End name space
247
248#ifdef HAVE_NAMESPACES
249}
250# ifndef NOT_USING_DJVU_NAMESPACE
251using namespace DJVU;
252# endif
253#endif
254#endif
255//T// Terminates the multiple inclusion #ifndef
256     
257     
258             
259
260   
Note: See TracBrowser for help on using the repository browser.