Hi,
I'm trying to get an overview of the LyX code again, and I thought I'd
try to clean up the documentation while I'm doing it. I started with
LyXTextClass (no particular reason for choosing that file).
I'm trying to figure out what each function/member does by reading
through the code. I'd appreciate it if people could let me know when I
get things wrong, as I inevitably will with the documentation in the
state its in.
The comments are formatted for doxygen. At the moment I'm using my own
custom doxygen configuration file, which also shows me graphical include
and inheritance relationships. Very nice! (This requires the dot
program, which comes in the graphviz package.)
Ben.
Index: src/ChangeLog
===================================================================
RCS file: /cvs/lyx/lyx-devel/src/ChangeLog,v
retrieving revision 1.970
diff -u -3 -p -u -r1.970 ChangeLog
--- src/ChangeLog 2002/11/05 18:25:53 1.970
+++ src/ChangeLog 2002/11/06 15:49:23
@@ -1,3 +1,7 @@
+2002-11-07 Ben Stanley <[EMAIL PROTECTED]>
+
+ * lyxtextclass.[hC]: add and clean up doxygen comments
+
2002-11-05 Lars Gullik Bjønnes <[EMAIL PROTECTED]>
* text2.C (updateCounters): fix bug 668
Index: src/lyxtextclass.C
===================================================================
RCS file: /cvs/lyx/lyx-devel/src/lyxtextclass.C,v
retrieving revision 1.21
diff -u -3 -p -u -r1.21 lyxtextclass.C
--- src/lyxtextclass.C 2002/09/11 07:39:55 1.21
+++ src/lyxtextclass.C 2002/11/06 15:49:23
@@ -47,7 +47,14 @@ struct compare_name {
} // anon
-
+/**
+ Construct a LyXTextClass and initialise to default values.
+ The actual .layout file is loaded later.
+
+ \param fn the name of the .layout file.
+ \param cln the LaTeX document class name.
+ \param desc the description of the document class.
+ */
LyXTextClass::LyXTextClass(string const & fn, string const & cln,
string const & desc)
: name_(fn), latexname_(cln), description_(desc),
@@ -111,7 +118,17 @@ enum TextClassTags {
};
-// Reads a textclass structure from file.
+/**
+ * Reads a textclass structure from file. May call itself recursively
+ * to read other included layout files.
+ * \param filename the name of the file to be loaded.
+ * \param merge If false, extra checks are made to ensure that the textclass is complete.
+ * The top level call must set merge to false (the default). Only recursive calls set it to true.
+ * \return true on error while reading the input files.
+ *
+ * \todo could this method be private?
+ * It's called by load, and it calls itself recursively.
+ */
bool LyXTextClass::Read(string const & filename, bool merge)
{
keyword_item textClassTags[] = {
@@ -744,7 +761,10 @@ bool LyXTextClass::delete_layout(string
}
-// Load textclass info if not loaded yet
+/**
+ * Load textclass info if not loaded yet.
+ * \return false if any error loading the textclass.
+ */
bool LyXTextClass::load() const
{
if (loaded)
@@ -760,8 +780,9 @@ bool LyXTextClass::load() const
<< "')\nCheck your installation and "
"try Options/Reconfigure..." << endl;
loaded = false;
+ } else {
+ loaded = true;
}
- loaded = true;
return loaded;
}
@@ -786,7 +807,7 @@ Counters & LyXTextClass::counters() cons
string const & LyXTextClass::defaultLayoutName() const
{
- // This really should come from the actual layout... (Lgb)
+ // \todo This really should come from the actual layout... (Lgb)
return defaultlayout_;
}
Index: src/lyxtextclass.h
===================================================================
RCS file: /cvs/lyx/lyx-devel/src/lyxtextclass.h,v
retrieving revision 1.10
diff -u -3 -p -u -r1.10 lyxtextclass.h
--- src/lyxtextclass.h 2002/09/11 07:39:55 1.10
+++ src/lyxtextclass.h 2002/11/06 15:49:23
@@ -17,20 +17,21 @@
#endif
#include "lyxlayout.h"
-#include "LString.h"
#include "lyxlayout_ptr_fwd.h"
#include "support/types.h"
-#include <boost/shared_ptr.hpp>
-
-#include <vector>
-
class LyXLex;
class Counters;
class FloatList;
-///
+/// Manages a LyX document.
+/**
+ * Contains all of the information required to display, edit and process a LyX document.
+ * This includes the document text, figures, formulae and other insets, the fonts used,
+ * the paper size, the screen layout used (as defined by the .layout file), and extra
+ * LaTeX packages which are required by the document.
+*/
class LyXTextClass {
public:
///
@@ -66,7 +67,7 @@ public:
///
LyXLayout_ptr const & operator[](string const & vname) const;
- /// Sees to that the textclass structure has been loaded
+ /// Ensures that the textclass structure has been loaded
bool load() const;
/// the list of floats defined in the class
@@ -114,18 +115,16 @@ public:
///
unsigned int columns() const;
- ///
+ /// Use one or two sides of the page?
enum PageSides {
- ///
OneSide,
- ///
TwoSides
};
///
PageSides sides() const;
///
int secnumdepth() const;
- ///
+ /// Depth to summarise document structure in the table of contents.
int tocdepth() const;
///
@@ -148,9 +147,9 @@ private:
bool delete_layout(string const &);
///
bool do_readStyle(LyXLex &, LyXLayout &);
- ///
+ /// The name of the file.
string name_;
- ///
+ /// The LaTeX document class name.
string latexname_;
///
string description_;
@@ -164,19 +163,19 @@ private:
string pagestyle_;
///
string defaultlayout_;
- ///
+ /// Lines added to the preamble by the .layout file.
string preamble_;
- ///
+ /// LaTeX packages that are already provided by the document class.
Provides provides_;
- ///
+ /// Number of columns of text on a page.
unsigned int columns_;
- ///
+ /// Use one or two sides of the page?
PageSides sides_;
- ///
+ /// heading depth before sections are no longer numbered.
int secnumdepth_;
- ///
+ /// heading depth to appear in the table of contents.
int tocdepth_;
- ///
+ /// outputType is LaTeX, ...
OutputType outputType_;
/** Base font. The paragraph and layout fonts are resolved against
this font. This has to be fully instantiated. Attributes
@@ -189,13 +188,13 @@ private:
/// Text that dictates how wide the right margin is on the screen
string rightmargin_;
- ///
+ /// The major section type.
int maxcounter_; // add approp. signedness
///
LayoutList layoutlist_;
- ///
+ /// The different kinds of floats (eg. figure, table, algorithm) supported by the document class.
boost::shared_ptr<FloatList> floatlist_;
///
