From 12646a5ae2b43a1954c8bd962328268ae564f1f6 Mon Sep 17 00:00:00 2001 From: Julian Smart Date: Mon, 13 Mar 2000 11:20:59 +0000 Subject: [PATCH] Added tech note on adding class documentation. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@6648 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/tech/index.txt | 1 + docs/tech/tn0003.txt | 205 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 206 insertions(+) create mode 100644 docs/tech/tn0003.txt diff --git a/docs/tech/index.txt b/docs/tech/index.txt index 03e1c4d925..12ddc25678 100644 --- a/docs/tech/index.txt +++ b/docs/tech/index.txt @@ -1,4 +1,5 @@ TN0001 How to add a new sample TN0002 wxWindows translator guide +TN0003 Adding wxWindows class documentation Version: $Id$ diff --git a/docs/tech/tn0003.txt b/docs/tech/tn0003.txt new file mode 100644 index 0000000000..7aab63066f --- /dev/null +++ b/docs/tech/tn0003.txt @@ -0,0 +1,205 @@ + Adding wxWindows class documentation + ==================================== + +This note is aimed at people wishing to add documentation for a +class to either the main wxWindows manual, or to their own +manual. + +wxWindows uses Tex2RTF to process Latex-like input files (.tex) +and output in HTML, WinHelp RTF and Word RTF. Tex2RTF is provided +in the wxWindows distribution and in the CVS archive, under +utils/tex2rtf. Please start by perusing the Tex2RTF manual. + +If adding to the existing manual in docs/latex/wx, you need to +create a new .tex file, e.g. myclass.tex, and add it to the +list of classes in classes.tex (in strict alphabetical order). +You may also want to write a separate topic file, e.g. tmyclass.tex, +and add the entry to topics.tex. + +If compiling a separate manual, copy an existing set of files from the +wxWindows manual or a contribution. Contribution documentation +normally goes in the contrib/docs hierarchy, with the source +going in a latex/mycontrib subdirectory. + +You can generate a first pass at the myclass.tex file by +compiling and running HelpGen (utils/helpgen). + +Running Tex2RTF +=============== + +See the Tex2RTF documentation, but here are some forms: + +For HTML: + + tex2rtf manual.tex manual.htm -html -twice + +Use of -twice allows Tex2RTF to resolve references. Note that +if both filenames are given (first two parameters on the command +line) then Tex2RTF will run in non-interactive mode. + +For WinHelp RTF: + + tex2rtf manual.tex manual.rtf -winhelp -twice + +For Word RTF: + + tex2rtf manual.tex manual.rtf -rtf -twice + +If you wish to generate documentation for wxHTML Help Viewer +(or Windows HTML Help), set htmlWorkshopFiles to true in your +tex2rtf.ini file. See also the wxHTML Notes section in the +wxWindows manual. + +src/msw/makefile.vc contains targets for generating various +formats of documentation. You may like to do something similar if +writing your own manual. + +Important Dos and Don'ts +======================== + +DO: + +- put a space (or \rtfsp) at the end of a line or start of a line where + a command ends or starts the line. Otherwise, spaces will be + omitted in Word or WinHelp RTF. For example: + + See \helpref{wxBitmap::wxBitmap}{wxbitmapconstr}\rtfsp + for a list of possible values. + +- leave a blank line at the end of the class file. This is + important, or the Word RTF table of contents will be messed up. + +- leave a blank line between a heading and the next paragraph. + +- test your changes, preferably converting the manual to WinHelp + format and running through the Windows help compiler to check + for missing labels, etc. + +DON'T: + +- use jargon, such as 'gonna', or omit the definite article. + The manual is intended to be a fluent, English document and + not a collection of rough notes. + +- use non-alphanumeric characters in labels. + +- use incompatible Latex syntax, such as {\it \bf word} (use a pair + of braces for each formatting command). + +- leave multiple consecutive blank lines, or blank lines between + \items in a list. + +Troubleshooting +=============== + +Please see the troubleshooting section in the Tex2RTF manual, but +here is one important tip: + + If you get a "Macro not found: \end{document}" error, + this is a spurious side-effect of an earlier error, usually an + incorrect number of arguments to a command. The location of the + true error is then anywhere in the document. + + To home in on the error, try putting \begin{comment}...\end{comment} + around much of the document, and then move the \begin{comment} + line down until the error manifests itself again. Note that + you can abort Tex2RTF after the syntax error stage by clicking + on the close button, so you don't have to wait while the whole + document is processed. + + Before looking at a file in detail, you can comment out the + \input{myclass.tex} line in classes.tex using the single + line comment character (%) to see whether it was that file that + caused the problem. + +Elements in a class file +======================== + +Start off with: + +\section{\class{wxMyClass}}\label{wxmyclass} + +(note that labels can only go on sections such as \chapter, +\section, \subsection, \membersection, but not on \wxheading, for +example.) + +Describe the class briefly. + +Then there are several \wxheading sections: + +\wxheading{Derived from} + +List the base classes, with line breaks following each one (\\) +except the last. + +\wxheading{Include files} + +List the relevant include files, for example: + + + +\wxheading{Predefined objects} + +List any predefined objects, such as: + +{\bf wxNullMyClass} + +\wxheading{See also} + +List any relevant classes or topics, using \helpref. + +\latexignore{\rtfignore{\wxheading{Members}}} + +This generates the required heading for the member definitions. +Put the constructors first, then in alphabetical order, the other +members. + +Here's an example of documentation for a member function: + + --------------------:x----------------------- + +\membersection{wxBitmap::Create}\label{wxbitmapcreate} + +\func{virtual bool}{Create}{\param{int}{ width}, \param{int}{ height}, + \param{int}{ depth = -1}} + +Creates a fresh bitmap. If the final argument is omitted, the display depth of +the screen is used. + +\func{virtual bool}{Create}{\param{void*}{ data}, \param{int}{ type}, + \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}} + +Creates a bitmap from the given data, which can be of arbitrary type. + +\wxheading{Parameters} + +\docparam{width}{The width of the bitmap in pixels.} + +\docparam{height}{The height of the bitmap in pixels.} + +\docparam{depth}{The depth of the bitmap in pixels. If this is -1, the screen depth is used.} + +\docparam{data}{Data whose type depends on the value of {\it type}.} + +\docparam{type}{A bitmap type identifier - see \helpref{wxBitmap::wxBitmap}{wxbitmapconstr} for a list +of possible values.} + +\wxheading{Return value} + +TRUE if the call succeeded, FALSE otherwise. + +\wxheading{Remarks} + +The first form works on all platforms. The portability of the second form depends on the +type of data. + +\wxheading{See also} + +\helpref{wxBitmap::wxBitmap}{wxbitmapconstr} + + --------------------:x----------------------- + +Note the use of \docparam to document parameters; and the fact +that several overloaded forms of the same member function are +documented within the same \membersection. + -- 2.45.2