More documentation. It never ends!

This commit is contained in:
Jordan Bancino 2023-04-29 19:52:51 +00:00
parent a08018870e
commit 872fa1aa66
5 changed files with 45 additions and 35 deletions

View file

@ -27,11 +27,11 @@ Milestone: v0.3.0
[x] Tls [x] Tls
[x] HttpClient [x] HttpClient
[x] Uri [x] Uri
[ ] td [x] td
[ ] tt [x] tt
[ ] http-debug-server [ ] http-debug-server
[ ] tp [ ] tp
[ ] send-patch [x] send-patch
[x] Log [x] Log
[x] TelodendriaConfig -> Config [x] TelodendriaConfig -> Config
[x] HashMap [x] HashMap

View file

@ -1,4 +1,4 @@
.Dd $Mdocdate: March 10 2023 $ .Dd $Mdocdate: April 29 2023 $
.Dt SEND-PATCH 1 .Dt SEND-PATCH 1
.Os Telodendria Project .Os Telodendria Project
.Sh NAME .Sh NAME
@ -10,16 +10,7 @@
.Sh DESCRIPTION .Sh DESCRIPTION
.Nm .Nm
is a simple shell script for submitting patch files to Telodendria's patch is a simple shell script for submitting patch files to Telodendria's patch
room for review. Do note that it depends on room for review.
.Xr json 1
and
.Xr curl 1 ,
and so may not work out of the box on some systems. However,
.Xr json 1
ships with Telodendria, and
.Xr curl 1
is readily available for most systems. Please consult your package manager's
manual for installing packages.
.Pp .Pp
.Nm .Nm
takes a single argument, a patch file. It also reads a number of environment takes a single argument, a patch file. It also reads a number of environment

View file

@ -1,4 +1,4 @@
.Dd $Mdocdate: March 10 2023 $ .Dd $Mdocdate: April 29 2023 $
.Dt TD 1 .Dt TD 1
.Os Telodendria Project .Os Telodendria Project
.Sh NAME .Sh NAME
@ -73,35 +73,43 @@ with a single invocation of
but recipes are run unconditionally; that is, even if a recipe fails, all the but recipes are run unconditionally; that is, even if a recipe fails, all the
following recipes are still executed. following recipes are still executed.
.Bl -tag .Bl -tag
.It docs
Build the code documentation files. While a good portion of the documentation
is written by hand and maintained in the
.Pa man/
directory, a substantial amount of documentation is stored in the C header
files that define Telodendria's APIs.
This recipe runs
.Xr hdoc 1
on each header to generate man pages for them. The man pages are place in
a directory that's already in your man path.
.It build .It build
Build the source code and generate the output binary. This is the default recipe, Build the source code and generate the output binary. This is the default recipe,
which means it runs if no other recipes are specified. This recipe is incremental; which means it runs if no other recipes are specified. This recipe is incremental;
it only rebuilds sources that have been modifed since the last build, making it only rebuilds sources that have been modifed since the last build, making
subsequent builds faster. subsequent builds faster.
.It run .It run
Run the build binary with the development configuration in the Run the built binary with the data directory of
.Pa contrib/ .Pa data/
directory. This recipe is used for quick testing during development. It is in the current directory. This recipe is used for quick testing during
development. It is
.Sy not .Sy not
the recommended way to run Telodendria in a production environment; it should only the recommended way to run Telodendria in a production environment; it should only
be used for development. be used for development.
.It clean .It clean
Remove the Remove the
.Pa build/ .Pa build/
directory and any ephemeral files in the source tree, such as directory. The build recipe does not place anything outside of
.Pa .orig
files. The build recipe does not place anything outside of
.Pa build/ , .Pa build/ ,
so you can usually just delete that directory and get the same effect. so you can usually just delete that directory and get the same effect.
.It install .It license
Install Telodendria to the system. This recipe assumes you're running a Update the copyright comments in every C source and header file using the
Unix-like system. contents of the
.It uninstall .Pa LICENSE.txt
Uninstall Telodendria from the system if it was installed with the install file. This recipe will also add the license header to new headers and C
recipe. sources that show up.
.It format .It format
Make sure the source code copyright headers are up to date, and format the code Format the code using the system's
using the system's
.Xr indent 1 . .Xr indent 1 .
This should be run before generating patch files, to ensure that the code follows This should be run before generating patch files, to ensure that the code follows
the project conventions. Note that the provided the project conventions. Note that the provided
@ -109,10 +117,6 @@ the project conventions. Note that the provided
assumes an OpenBSD indent, which may cause the GNU implementation to choke. In assumes an OpenBSD indent, which may cause the GNU implementation to choke. In
that case, don't send patch files with totally different formatting; just submit that case, don't send patch files with totally different formatting; just submit
the patch as-is and they will get formatted before committing. the patch as-is and they will get formatted before committing.
.It test
Run all of the unit tests and report the results. It is highly recommended to
ensure that all the tests pass before submitting a patch, because patches that
break the tests are likely to be rejected.
.It site .It site
Deploy the Telodendria website by generating HTML files for the documentation, Deploy the Telodendria website by generating HTML files for the documentation,
and copying them along with the front page to the specified web root. This is and copying them along with the front page to the specified web root. This is
@ -165,10 +169,22 @@ so with this environment variable.
.It Ev LDFLAGS .It Ev LDFLAGS
The compiler flags used to link the object files to create an output The compiler flags used to link the object files to create an output
binary. binary.
.It Ev LD_EXTRA
The common, well-known compilers support a number of extra flags that
smaller, niche compilers probably will not. This variable holds those
flags, so if you are compiling with a small, lesser known compiler, you
can set this to an empty string to disable the extra flags.
.Pp
.Nm .Nm
comes with reasonable defaults that shouldn't need to be changed in most comes with reasonable defaults that shouldn't need to be changed in most
scenarios, but if you need to change the linker flags, you do so with this scenarios, but if you need to change the linker flags, you do so with this
environment variable. environment variable.
.It Ev TLS_IMPL
Set the TLS implementation library to use for Telodendria's TLS
support. Consult
.Xr Tls 3
for a list of supported implementations. Implementations should be
specified by name in all uppercase.
.It Ev PROG .It Ev PROG
The name of the output binary. This defaults to The name of the output binary. This defaults to
.Pa build/telodendria. .Pa build/telodendria.

View file

@ -119,9 +119,12 @@ pages are also available online for convenience:
</p> </p>
<p>User Documentation:</p> <p>User Documentation:</p>
${USER_DOCS} ${USER_DOCS}
<p> <br>
<details> <details>
<summary>Developer Documentation:</summary> <summary>Developer Documentation:</summary>
<p>
This documentation is intended primarily for developers. It details all
of the internal workings of Telodendria.
</p> </p>
${DEV_DOCS} ${DEV_DOCS}
</details> </details>

View file

@ -24,7 +24,7 @@
#ifndef TELODENDRIA_REGTOKEN_H #ifndef TELODENDRIA_REGTOKEN_H
#define TELODENDRIA_REGTOKEN_H #define TELODENDRIA_REGTOKEN_H
/** /***
* @Nm RegToken * @Nm RegToken
* @Nd Manage Matrix client registration tokens. * @Nd Manage Matrix client registration tokens.
* @Dd April 29 2023 * @Dd April 29 2023