Fix #228 Improve GitHub and Doxygen Docs. by dbaarda · Pull Request #230

Fix #228 Improve GitHub and Doxygen Docs. by dbaarda · Pull Request #230 · librsync/librsync

added 6 commits

August 20, 2021 17:23

Rename test input files, update test scripts, and update `.gitattributes` to
treat `.input` files as binary, not `.in` files.

This prevents cmake input templates ending in `.in` from being treated like
binary test data files. In particular `doc/Doxyfile.in`.

This makes the name more consistent with other cmake template files.

Set `HAVE_DOT = YES` and `DOT_IMAGE_FORMAT = svg`. FTR I compared and svg
diagrams are smaller than png as you would expect.

Make the doc target run in CMAKE_CURRENT_SOURCE_DIR and change `Doxyfile.in`
to generate output into `OUTPUT_DIRECTORY = @CMAKE_CURRENT_BINARY_DIR@`.

This ensures consistent doc filenames and references when using different
build directorys, without leaking the full path of where it was built. See

Newer doxygen versions on Debian testing were complaining about this missing
argument docstring entry in librsync.h.

This mostly just reformats paragraphs but also uses markdown links for root
docs CONTRIBUTING.md, NEWS.md, and TODO.md instead of Doxygen `\ref` links.

The root docs don't have `{#anchor}` doxygen anchors which is a pre-requisite
for markdown links to work on the old ubuntu_latest version of Doxygen. Note
currently CONTRIBUTING.md does have an anchor, but I want to test that it
actually fails before removing it.

Currently this document is only referenced by a markdown link in README.md,
and for the old ubuntu_latest Doxygen version markdown links don't work if the
doc has an anchor.

This makes the anchor name more consistent with the filename. Also change the
title to be more consistent with the other usage doc rdiff.md.

This makes the anchor more consistent with the other docs.

This makes the anchor name consistent with the filename.

This makes the filename consistent with the doxygen anchor name.

This makes the title more consistent in the context of the other docs, and
avoids confusion around callbacks used for other current (or future) APIs.

This is more consistent with other document titles and makes neater `\ref`
links.

It seems a4wide is not supported in newer doxygen versions on Debian and is
giving a warning.

This also makes the doxygen `\ref` links a little nicer.

Move doxygen docs from `*.c` files to their corresponding `*.h` files if there
is one. Remove any "private" or "internal" markers from docs. It's already
clear the librsync.h is the only public interface, but the rest of the docs
are useful for understanding the code so we still want to generate them.