source: trunk/libdjvu/Template.h @ 15

Last change on this file since 15 was 15, checked in by Eugene Romanenko, 15 years ago

needed libs update

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