Difference between revisions of "Documentation Primer/Manual/DocBook Reference/Programming"

Latest revision as of 12:07, 9 September 2012

Other languages:

English

[edit] Markup for programming

For formally marking up code examples or making a synopsis, you should study the Duck Book and the The synopsis elements chapter. The elements described below are mainly for marking up of pieces of source code that appear in the running text. Remember that KDE and KDE applications are written almost exclusively in C++, so our useage may differ in places from the examples in the Duck book, which may be describing other programming languages.

To Developers reading this, remember most of the authors who may be documenting your work are unfamiliar with source code, and many of them like it that way. Therefore, the explanations here are more concerned with how to tell things apart than what they are for, and may make you cringe.

To everyone reading this, this section is very much under construction so to speak. If you already need to use this markup, you can ask questions on the kde-docbook mailing list, which is the most likely place to get correct and up to date answers.

<classname>

Used to identify the name of a class in a programming language. In KDE Documentation, you won't see this much in the user documentation, except for those applications which contain an API reference chapter, and occasionally in others. You will find it used a lot in the KDevelop documentation.

For non-programmers, as we're almost exclusively discussing KDE applications written in C++ and using Qt™, classnames are fairly easy to distinguish: They start with a capital Q or K, and are usually one word only, in the form of KApplication or QListBox.

<function>, <methodname>

A function or "subroutine". In C++, a function generally looks something like this: foo();. The semi-colon may not always be present and there may or may not be content inside the braces.

If you see things that have the form Kfoo::bar() these are not just functions, but also methods, so you would use the <methodname> for these.

Constructors are methods where the parts before and after the :: are the same, e.g. KFoo::Kfoo(). Destructors look like Constructors, but have a ~ after the :: e.g. Kfoo::~Kfoo(). The same things apply as with functions and methods: there may or may not be a ; at the end, and there may or may not be content inside the braces of a constructor (there is never content for a destructor).

These are normally marked up as <methodname>, but if you need to make a synopsis of a method, there are specific elements available: <constructorsynopsis> and <destructorsynopsis>

To recap:

Function

foo()

Methodname

Kfoo::bar()

Constructor

Kfoo::Kfoo() These are methods in ordinary text, but when making a synopsis, have a more specific tag to use.

Destructor

Kfoo::~Kfoo() These are methods in ordinary text, but when making a synopsis, have a more specific tag to use.

Sometimes you really cannot tell the difference, especially when they are being mentioned in passing in the text. Also, programmers tend to shorten and make shortcuts when referring to snippets of source. If it's very unclear what something is, mark it up with <function> and ask the developer.

 

Tip
Asking a developer "What is foo?" will likely result in a two page explanation of a finer point of C++ programming, which, if you could understand it, you wouldn't have needed to ask the question in the first place. It saves everyone a lot of time and frustration if you word the question "Out of function, method, constructor and destructor, which is the best fit for foo?".

<varname>

The name of a variable.

<returnvalue>

The value returned by a function.

<token>

A token is a placeholder, something that is replaced by an actual value during processing. (I need to come up with a useful example for a token)

<constant>

A constant. In the snippet:

enum MyType { Red = 0, Green, Blue, Yellow };

Red, Green, Blue and Yellow should be marked up as <constant>

<type>

Used to classify a value. In the snippet:

enum MyType { Red = 0, Green, Blue, Yellow };

MyType is a <type>

<programlisting>

Use this to wrap any source code examples in your document. You don't need to use this for short snippets that are inline in the text, but you should use it for any examples longer than a line or two, or that are a separate block of text.

<structname>,<structfield>

Not used in KDE Documentation, primarily because they are rare in KDE source code, and are almost certainly never going to require marking up.

<parameter>

Parameters can be used for commandlines as well as for code samples.

<classsynopsis>

A class synopsis

DCOPStub {
? not sure about what goes here ? enum Status(''CallSucceeded'', ''CallFailed'');
}

<initializer>

An initializer

<exceptionname>

An exception name

• ← The synopsis elements
• ↑ Back to Menu ↑
• Making Callouts →