This provides targets for some of the doxygen links, and some of
them have useful memberof function lists.
Added some if/else statements to reduce validation errors.
Tested-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
All the methods belonging to the class are listed with it, making
it much easier to find them.
I dumped all other functions into a section called "Functions" at
the end.
Tested-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Just to make it slightly shorter.
Also add a dash to the doxygen links to make them look a bit more alike.
Tested-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
(this is different from previous version as it removes some
broken and irrelevant changes to the protocol appendix).
This removes all the validation errors except for missing link
targets. You can test this by removing the --skip-validation
from doc/publican/Makefile.am.
Main changes are to avoid nesting <para> commands. I also used
<simpara> in some places to reduce the amount of blank space.
And the reference id's are prefixed with the chapter name to
avoid collisions between libclient and libserver.
PS: it would be useful if somebody who actually knows something
about xslt would come up with a way to translate a block of text
makde of <para> commands unchanged, but add <para> around plain
text. Most of the difficulty is that doxygen's output is rather
inconsistent here.
Tested-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
The repetitive parts of generating the server and client documentation are
merged, so it is easier to add another doxygen chapter: add a new line to
$publican_sources in publican/Makefile.am, and a list of C source files to
doxygen/Makefile.am.
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
Move the *_8h.xml files to a per-chapter temporary file so two
chapters can be converted from doxygen at the same time. Tested
with make -j 9.
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
This was suggested before to make it clearer that things like wl_display
are different objects in each of them. I made these into two appendixes
because the protocol spec was already an appendix.
Reviewed-by: Bryce Harrington <b.harrington@samsung.com>
[Bryce requested minor changes, not yet here.]
Acked-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
It was telling it to scan the doxyfile as well as the C source, and
listing some source files more than once.
Reviewed-by: Bryce Harrington <b.harrington@samsung.com>
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Split out directory creation to leverage order only prerequisites.
Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com>
Acked-by: Peter Hutterer <peter.hutterer@who-t.net>
Acked-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
This is a general cleanup of the makefile in order to bring it more inline
with standard make practices. Cleanups included more use of automatic
variables, switching AM_V_GEN to AM_V_at to have one 'GEN' visible per file,
splitting copy operations to proper rules, and using order only dependencies
to properly create directories on-demand.
Changes also correct missing use of $(builddir) that has gone unnoticed as
it defaults to the current directory ('.').
Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com>
Acked-by: Peter Hutterer <peter.hutterer@who-t.net>
Acked-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
This text is a duplicate of the text in the protocol documentation, but
the converter mangled it by removing the paragraph breaks and some other
errors. Instead replace it with a list of links to the protocol docs.
Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net>
Invoke doxygen via the autoconf-defined make variable instead of directly.
This brings it in line with standard makefile practices.
Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com>
Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net>
Removed <xsl:output> elements that were duplicated but with attributes in
a different order. Standard tools are required to ignore the order of
attributes in an element.
Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com>
Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net>
These links are pretty useful for navigation, though sometimes excessive
(you can turn them off by putting % before the word in the comment).
I had to turn off validation because it failed on missing and duplicate
target id's, which this produces.
Doxygen represents all spacing in code blocks with <sp/> tags, so these
need to be turned back into spaces.
Signed-off-by: Benjamin Herr <ben@0x539.de>
xsl:value-of would strip all the nested markup of the selected doxygen
elements, so that \ref, \sa and \code formatting didn't actually work.
Signed-off-by: Benjamin Herr <ben@0x539.de>
Publican isn't packaged for some distros, xmlto is a lot more common. Most of
what publican provides for us is the stylesheet anyway, so we can just use
xmlto and the publican stylesheet to get roughly the same look.
PDF and XML generation has been dropped, this needs a bit more more effort
than a mere switchover to xmlto.
The top-level directory structure imposed by publican is kept for now
(specifically the Wayland/en-US/html tree). This makes it easier to transition over
for packagers. Note that the list of files inside has changed.
CSS files are taken from publican to keep a uniform look compared to previous
documentations. Stylesheets are licensed under CC0 1.0 Universal license, see
publican/LICENSE:
1. Files in the datadir/Common_Content directory and its subdirectories are
licensed under the CC0 1.0 Universal license.
To the extent possible under law, the developers of Publican waive all
copyright and related or neighboring rights to the files contained
in the datadir/Common_Content directory and its subdirectories.
Acked-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
The shell command for dist_man3_MANS gets invoked several times during
the make process but before the man pages have been generated, which
causes the following warnings when running `make`:
find: `man/man3': No such file or directory
find: `man/man3': No such file or directory
find: `man/man3': No such file or directory
GEN xml/client/index.xml
Despite these error messages, the generated dist tarball contains the
man3 pages as intended, both before and after this patch.
$ make dist
$ tar xxf wayland-1.5.90.tar.xz
$ find wayland-1.5.90/doc/doxygen/man/man3 -name "wl_*.3" | wc -l
85
Signed-off-by: Bryce Harrington <b.harrington@samsung.com>
Acked-by: Peter Hutterer <peter.hutterer@who-t.net>
Tested-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Traced down to the server/client target always rebuilding, causing a rebuild
of everything else. Rework this so the target name is a file we actually
produce and can check for a timestamp.
Note: this also changes the generated file from the doxygen directory into the
en-US publican path and renames it to (server|client)API.xml.tmp to avoid
copying it into the xml output directory.
I suppose the purpose was to print just one GEN line for each doxygen
rule being executed, not print the doxygen command.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
The doxygen.man make target was not a real file that was generated,
therefore the man page rule was ran on every make invocation. Replace it
with a real file that is produced by the man page rule.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Since /* */ do not nest, documentation is forced to either use C++ style
// comments or some other foreign notation. This commit provides an alias
that allows C-style comments to be introduced in code blocks that support
aliases.
It should be noted that this macro will not work within \code blocks, as
Doxygen commands are ignored there. Instead, Doxygen's fenced code
blocks (created via ~~~) must be used for proper output. To demonstrate:
~~~
struct example_node {
int id;
\comment{Other members ...}
};
~~~
will roughly yield the following HTML (excluding syntax highlighting):
<pre>
struct example_node {
int id;
/* Other members ... */
};
</pre>
This commit creates a shared file list that is included by both the
client and the server for the XML Makefile targets, as classes within
util are used by both the client and the server.
There have been a lot of questions asked lately about versioning of
interfaces and protocol objects. This addition to the documentation should
clear up some of those questions.
Signed-off-by: Jason Ekstrand <jason@jlekstrand.net>
The method described of alocation IDs has been wrong at least since version
1.0. This commit updates it to correspond to the way IDs are chosen in
versions >= 1.0.
Signed-off-by: Jason Ekstrand <jason@jlekstrand.net>
When generating HTML, don't split once we're into subjections. This
generates a single page for each protocol interface instead of the previous
separate pages for requests, events and enums.
No effect on the rest of the HTML configuration.
Document what we expect in terms of commit messages and coding style.
New contributors are usually unaware of this, so it is good to have a
document to point them too.
This requires that doxygen is run before the man target so find can actually
find the man pages.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Originally written Tiago Vignatti <tiago.vignatti@intel.com>
Some modifications to adjust for previously merged conflicting patches and link
to the sections (instead of <emphasis>).
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
The only difference between the server and client xml files is the
directories and files being named *server* and *client*, respectively. Add a
new make target to get that process done to avoid duplication
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Same as WaylandClientAPI.xml we now also generate WaylandServerAPI.xml for
publication. Most of this hunk is just adding a client/ or server/ into the
xml path to keep the two separate.
The change in wayland.doxygen now causes a standard doxygen call to not
generate anything - what is generated is specified through the options
passed by make.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Signed-off-by: Tiago Vignatti <tiago.vignatti@intel.com>
Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net>
[re-run of search/replace after rebasing]
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
