File: README.md

package info (click to toggle)
postbooks 4.10.0-2
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 112,660 kB
  • ctags: 22,890
  • sloc: cpp: 310,358; sh: 607; xml: 214; python: 140; awk: 104; makefile: 50
file content (73 lines) | stat: -rw-r--r-- 2,676 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
## Dependencies:

- You must have Doxygen 1.6 or later
- You must have the Qt docs installed in `QTDIR/doc/html`

## Steps to run:

```Shell
  $ git clone https://github.com/xtuple/qt-client
  $ git clone https://github.com/xtuple/qt-sample-scripts
  $ cd qt-client
  $ git checkout the_proper_build_branch_or_tag
  $ qmake
  $ make
  $ edit utilities/doxygen/Doxyfile.public
      # set PROJECT_NUMBER to match version.cpp
      # fix the URL in TAGFILES to match the Qt version we're using
  $ doxygen utilities/doxygen/Doxyfile.public
```

Then publish the resulting `html` directory via the `desktop-programmer-ref` directory in [xtuple.github.io](https://github.com/xtuple/xtuple.github.io).

**Note:** The `make` step above is important. It compiles the `.ui` files, which in turn allows Doxygen to document the screen fields.

## Doxygen comment guidelines

- Document in the `.cpp` file instead of the `.h` as much as possible.
- If the only items in the `.cpp` are class members, start the file with `@class`. Precede globals and statics in the `.cpp` with `@addtogroup` and wrap them in `@{` and `@}`.
- Use `/**` to start doxygen comments, not `/*!`
- Use `@`-style directives, not backslashes
- Use `@brief` instead of relying on Doxygen to guess.
- Put `%` in front of words that you're using casually that happen to be names of classes/functions/... so they don't get converted to links.
- Tag order is important. Put the tags you use in the following order:

```
/** @brief Short description of methodX.

    Long description of methodX.

    @dontinclude samplefile.js
      bits of samplefile.js using @skip, @until, ...

    More long description

    @param x Describe x

    @return Description of return value and its semantics

    @see RelatedClass
    @see samplefile.js
 */
int methodX(QString x) { ... }

/** @example */
```

## TODO

Look at turning on `COLLABORATION_GRAPH`. This would be more useful
for people working in the core. One problem with it, though, is
that the diagrams are really hairy - we have a lot of interdependencies.
On the other hand, this would provide good data on ways we could
simplify the code.

Look at turning off `EXTRACT_ALL` once we've documented everything.

Look into documenting stored procedures. We might have to write a
parser for PL/PGSQL and a filter to convert `--` comments to C- or
C++-style comments. The filter could be run on all source files
with a `.sql` suffix.  We might be able to do the same with `COMMENTS`
on tables and their columns and/or views and their columns. Either
we should create `COMMENTS` on functions or include Doxygen comments
inside the function text so they're always visible.