axiom-developer
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Axiom-developer] database fixes


From: Gabriel Dos Reis
Subject: Re: [Axiom-developer] database fixes
Date: 20 Oct 2006 17:15:15 +0200

Waldek Hebisch <address@hidden> writes:

[...]

| Hmm, I do not think information from the e-mail belongs to the
| document -- for example writing a paper I discard many alternatives
| and failed attempts and publish only final version. IMHO information
| about specific problem belongs to the ChangeLog (in form of a
| pointer to the message).

I see ChangeLog as a brief record to assist in archeology.  It is no
substitute for proper documentation.  It is not where code
documentation will go.

| Now if you think that what I wrote in the
| email needs extra record or additions I may register a bug.
| 
| > I probably would not have written:
| > 
| >   We also reset [boot::*allconstructors*]] to [[nil]].
| > 
| > Instead the text should say why we do that.
| 
| You, Gaby and Tim ask way.

That, in fact, matches practice in any large project I've worked in
including GCC -- I mention GCC because I know you read GCC list. 

[...]

| I can think of to changes to documantation: one is to say that
| all five openxxxx routines must be called together (because
| otherwise database gets out of sync). The second is that there
| is no need to have cleanup in browseOpen, because interpOpen
| should have already cleaned up old data.

see? :-)

Thanks,

[...]

| Maybe another point: Axiom has parts that really need better
| documentation -- Bill Burge parser would be first example,

which of his parser?

while sitting here watching the debate about whether ++0x should have
a module system, I was documenting src/boot.  

| Spad compiler the second.

I would put the SPAD compiler first :-)


| Compared to them daase.lisp.pamphlet
| contains strightforward and well documented code.  Also
| daase.lisp.pamphlet seem to work quite well compared to other
| parts of Axiom, so I see little reason to change it _now_ (except
| for this single patch which affects other things that I want
| to do) -- other parts need more care. 


hat is asked is that as you go and modify that function, please also
include the explanation of the why.  It is not being asked that your
changes be accompanied by the documentation of unrelated topic.

-- Gaby





reply via email to

[Prev in Thread] Current Thread [Next in Thread]