Distributing CL source code?

[wvxvw]

Hello. I don't have anything to *surprise* the humanity yet but I think it would be a good practice to organize the project in a way it is common for other people to do.
So, say and I wanted to provide source code to someone and some means of compiling it and testing, how would I do that? What am I expected to do myself, and what should I leave for others, who potentially may use my code?
So, for example, if the project is supposed to compile to binaries, I'd have to have a build script, what are the conventions? Do I have to add a .make file? Shell scripts? Ant? When installing with asdf-install I remember that some libraries provided a way to test them immediately after they are installed - I think this is a very good idea, but how would I do that?
How much documentation is considered *good enough*? Is there a documentation compiler (a program that would collect variables, functions, classes etc and their documentations and produce HTML / man / info / whatever other format)?

Is there an example project, you could point finger and tell it's just as everyone would expect a normal CL project to be? (at googlecode / github)

Thanks!

[ramarren]

So, for example, if the project is supposed to compile to binaries, I'd have to have a build script, what are the conventions? Do I have to add a .make file? Shell scripts?

Projects compiling to binaries are not that common in the first place. I have seen makefiles used occasionally.

When installing with asdf-install I remember that some libraries provided a way to test them immediately after they are installed - I think this is a very good idea, but how would I do that?

You can define a method on asdf:perform generic function specialized on test-op operation and your system. It isn't that commonly used and I don't think there is a standardized method of reporting failure. Testing serves more a role of refactoring aid than a compilation integrity check.

How much documentation is considered *good enough*?

Opinions vary. Some people say that source code is documentation enough, and if it is not, then it is written badly. At least some documentation is usually helpful though.

Is there a documentation compiler (a program that would collect variables, functions, classes etc and their documentations and produce HTML / man / info / whatever other format)?

There are several, but personally I don't really like them. Programmatic documentation is more suitable to be accessed from an IDE, while external documentation is better off hand written.

Is there an example project, you could point finger and tell it's just as everyone would expect a normal CL project to be? (at googlecode / github)

I have several projects on my GitHub, although I haven't really worked on any of them recently. Most of them are in various states of usefulness, but parser-combinators and png-read are included in quicklisp. They are all libraries. I actually haven't seen that many actual open source Common Lisp applications. Although StumpWM comes to mind. Also Maxima. Those are fairly large projects, though.

[wvxvw]

Oh, ok, thanks for the links.
One thing though re' the documentation: what I meant is for example: symbols not externed may not be commented, or, when commented, which are the features one must put into documentation? I.e. I would guess what one would be looking for in function / variable definition, but I've no idea how to comment a macro. Or, if you are using several reader macros, but you are using them exclusively in one file, but not another, would you put all macros in one file, regardless they aren't used together, but simply based on the fact they are all macros that modify the way the code is interpreted, or you would put the macro definition next to where it used? (I've this example: http://mxr.mozilla.org/mozilla/source/js2/semantics/ all the macros are in Utilities.lisp file).
Another thing which confuses me: I see that quite often even if the form has special place for documentation (like defclass / defgeneric etc.) people choose to put documentation in the source file itself, not into the declaration - why would anyone do it one way and not another?

[smithzv]

I see that quite often even if the form has special place for documentation (like defclass / defgeneric etc.) people choose to put documentation in the source file itself, not into the declaration - why would anyone do it one way and not another?

I think that docstrings are for the users of your program, comments in the code are for people hacking on your program. The two are different practices, though one can often lead to the other. A docstring should tell you how to use something. Comments should help people to understand how the program is working.

but I've no idea how to comment a macro

I don't fully understand this. A macro is just a function at its heart, albeit one that runs with the parse tree as it's arguments. You comment it like a function; describe what it is used for. The only thing different is macro documentation also needs to specify how it changes the syntax.

if you are using several reader macros, but you are using them exclusively in one file, but not another, would you put all macros in one file, regardless they aren't used together, but simply based on the fact they are all macros that modify the way the code is interpreted, or you would put the macro definition next to where it used?

A lot of differing opinion on this. I think that encapsulation is the most important thing. If my macros are used in just one file, I would want my definition to be as close to where it is used as possible. Then again, who cares. Now-a-days, using Slime and M-. or a TAGS file with other editors (probably lots of ways to do this), anybody can jump to the definition of any macro/function/variable. Just organize things however it works for you.

[wvxvw]

Regarding the macro vs function documentation difference: function would need arguments types, return type / errors if any. Reader macro is something that takes obvious parameters (you don't really need to comment on that), and it's obvious what it returns, but it may make changes to the way other objects are read inside the macro, well, I don't even really know the right word to call it That's maybe why I'm asking. Well, say and the macro adds an ability to read #?01234...9 as Unicode characters, so you would need to tell something to other people who are using your code that they would both know that:
if they eventually expected this syntax to mean something else in another place, they should beware of the change. Or, let's say, some print-object method turns on *circle-print* - this is not obvious from parameters, but it may be very important if your object is suddenly not printed the way you expected.
So, I see in the spec often times there's a paragraph called "side effects" or something like that. Basically, what I wanted to know is: things per declaration you would expect to be commented, by groups, like:
commenting a function requires argument types, return types, errors / conditions, side effects.