@MSGID: 1@dont-email.me> d1773d8c
@REPLY:
<cfef6de1-b912-42d3-9fa7-5d58e911bd66n@googlegroups.com> 781b8425
@REPLYADDR Rich <rich@example.invalid>
@REPLYTO 2:5075/128 Rich
@CHRS: CP866 2
@RFC: 1 0
@RFC-Message-ID: 1@dont-email.me>
@RFC-References:
<cfef6de1-b912-42d3-9fa7-5d58e911bd66n@googlegroups.com>
@TZUTC: -0000
@PID: tin/2.6.1-20211226 ("Convalmore")
(Linux/5.15.117 (x86_64))
@TID: FIDOGATE-5.12-ge4e8b94
stk <skuhagen@web.de> wrote:
> *Documentation:*
> I`d like to use Doxygen, but not sure, if this is still a good 
> option, since Tcl is not supported anymore.  Whats your preference?  
> My goal is, to document the API of my project in source and generate 
> it into HTML automatically.

Personal opinion here, but in every case I can think of where doxygen 
was used to "autodocument the source" the resulting docs were no more 
valuable than simply reading the source (in fact, often less valuable).  
The doxygen html would tell you that there were these twelve C 
functions you could call, and that their parameters were X, Y, or Z, 
but leave off what the function did (I guess the author`s though their 
names were meaningful enough) and more often than not, leave off any 
description of what was expected of the parameters.

Now, this might have been a failure of the author to insert enough 
"doxygen tags" into the source to generate proper docs, but as I saw 
the pattern with *every* one I remember, it felt more like doxygen 
existed merely to satisify some corportate code review checkbox for 
"auto-generated code documentation" where the code review checkbox 
omitted a second checkbox of "and the output documentation is useful to 
someone for the purpose of learning/using the API).

> *Tcl-packages:*
> The first implementations (there are three at this time...) used 
> Tcl-packages to split the whole thing into architecture components.  
> A main package that loaded all the others in its init-part and then 
> provided the Rivet-Apache-plugin as package which was used in a small 
> Rivet-script that just passed on the HTTPS-request to my package.
> 
> The whole package hierarchy did not start at global namespace "::" 
> but as "myPackage::mod1::...".  The idea was, that this way it would 
> be possible to use "require package" in a namespace and thus use the 
> whole thing not in global namespace but where convenient.  For 
> refactoring I`m now considering, if starting globally as 
> "::myPackage::mod1::..." is better or not?  Is there a best practice 
> regarding that?

I don`t think this will matter much.  Most scripts do their package 
requires at the top level of the initial script and so they are "at 
global level" anyway.  Not forcing global level makes the package 
slightly more flexible, but perhaps a documentation note of the 
fexibility would be in order.

> *Rivet vs. Standalone:*
> This is almost decided, but maybe you have some good input here: I 
> think, I will get rid of using Rivet-apache-module.

I feel that if you do so you will find yourself eventually adding back, 
as custom code you have to write yourself, much of what Rivet provides 
to you if you go this route.

If that is what you want, then go for it.  But if your focus is the 
blog system, not the underlying web plumbing, then keeping Rivet may 
prove better in the end.

> *Procs in namespaces vs. namespace ensembles:*
> Ensembles feel kind of elegant to me, but by default, I mostly just 
> write procs in namespaces, although related procs could go into an 
> ensemble - so much for clean APIs...  But then I`m not sure about the 
> name resolving performance of ensemble commands vs.  direct proc 
> call.

Tcl has a very useful [time] command.  Test, on your hardware and with 
your code the performance of both and see what you get.  Then you won`t 
be guessing, but will have actual data.

--- tin/2.6.1-20211226 ("Convalmore") (Linux/5.15.117 (x86_64))
 * Origin: A noiseless patient Spider (2:5075/128)
SEEN-BY: 5001/100 5005/49 5015/255 5019/40 5020/715
848 1042 4441 12000
SEEN-BY: 5030/49 1081 5058/104 5075/128
@PATH: 5075/128 5020/1042 4441