This is the mail archive of the guile@cygnus.com mailing list for the guile project.
Index Nav: | [Date Index] [Subject Index] [Author Index] [Thread Index] | |
---|---|---|
Message Nav: | [Date Prev] [Date Next] | [Thread Prev] [Thread Next] |
jimb@red-bean.com writes: > > Did you ever read over the Java class documentation in the early days > of Java? They had it on the web. It was terrible. You couldn't > figure anything out. That's one example I have of a manual extracted > from docstrings. I also know that Stallman was quite opposed to the > idea, and over the years I decided he was probably right. > It definitely sucked, but I think we can do better. I think the main reason it sucked was because it was organized solely be the class names and package hierarchy, rather than in any logical way. I mean, if I knew the name of the class I wanted and the package it was hiding in, I probably didn't really need the manual that much anyway. Another problem is that there was only a reference manual, and no decent user manual providing task-oriented examples. > It's just a gut feeling. If you don't agree, you don't agree, and > you should go with your own gut feeling. > I trust your experience in this area, and I agree with many of your specific concerns. But I also think we have a way of addressing some of them, and I think the benefit is worth it. > > Or, if you think it is valuable to have the text mingled with the > source code, add a notation to your manual format that says "extract > the docstring for this function from the source, and insert it here." > That way, the layout of the source has no influence on the layout of > the manual. > Well, I don't think the layout of the source should dictate the layout of the manual, for the reasons you cited. As I said before, I think the hierarchy of the manual needs to be externally imposed, because, as you said, the program's logical layout will not necessarily match the manual's. If documentation of code implemented in C and in Scheme need to be combined in one place, for instance, there's no possible way to restructure the program to get this in one file. However, I am not sure something as extreme as writing a manula skeleton with special notations to extract the specific documentation is necessary. Perhaps it is, and if it comes to that, I still think it is a superior solution to extracting docstrings from the manual, for the reasons below. > > Do people feel that, if the documentation is a separate file, > programmers will be discouraged from writing docs, whereas, if the > documentation were mingled with the source, then programmers would > naturally write docstrings as they go along? This is the primary motivation to me. First, it helps get the manual off the ground in the first place. If I look at the old outdated crufty manual, I think "It sure will be a lot of work to get this to match the current code." But if I can incrementally add docstrings and get continually improving documentation as a result, I'll be a lot more motivated. I think it also makes maintenance of the docs a more automatic thing. It makes the transaction cost of updating the docs when you change the program much lower, and it makes it a lot easier to remember to do so (and perhaps makes you feel guilty when you don't), since all the surrounding code will be annotated already. The problem of coming up with a good manual _structure_ starting with all this point documentation is not triviall, but I think it is well worth the effort. - Maciej