This is the mail archive of the guile@sourceware.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] |
On 19 May 2000, Keisuke Nishida wrote: > Another alternative: > > SCM_DEFINE_SCHEME_OBJECT > SCM_DEFINE_SCHEME_STATIC_OBJECT > SCM_DEFINE_SCHEME_SYMBOL > SCM_DEFINE_SCHEME_STATIC_SYMBOL > SCM_DEFINE_SCHEME_KEYWORD > SCM_DEFINE_SCHEME_STATIC_KEYWORD > > This is more clear, but a little bit verbose... I like it better than the SCM_CREATE_ and SCM_MAKE_ variants. Maybe some other folks from the guile list do also have an opinion on that? If not, I'd say that we take the above solution. (Although I'm still in doubt whether the SCHEME infix is necessary...) > After this, the user may write whatever she likes: > > SCM_SNARF_HERE(static scm_foo); > SCM_SNARF_INIT(scm_foo = scm_bar); > SCM_SNARF_DOCS("scm_foo", c_variable, "This is foo..."); I'd like it better if the user would never have to use a SCM_SNARF_ macro, no matter what. But, with the availability of all those SCM_DEFINE_ macros, there is really little need for additional documentation macros, so it is nothing that we have to decide urgently. > > Maybe SCM_DOCUMENT_CONCEPT would also be nice for adding documentation > > of basic concepts, but not a lot more I think. > > Well, I think simple concepts (e.g., "What is fluid?") can be documented > with some appropriate procedures (e.g., fluid?). More complex concepts > should be documented separately, in my opinion. (With 'but not a lot more' I didn't mean that SCM_DOCUMENT_CONCEPT was only suitable to document simple (basic) concepts, but I rather meant that we don't need a lot more additional documentation macros than SCM_DOCUMENT_C_MACRO and SCM_DOCUMENT_CONCEPT. Sorry for the confusion.) Documenting simple concepts together with some 'appropriate' procedure is the way that it is currently done, but IMO mostly due to the fact that there is no other way of doing it yet. In the long term, I believe that we can come to a more sophisticated way of documenting things that for example makes use of crossreferencing. Then, it would be better to be able to crossref-reach the 'fluids' concept documentation from _all_ functions that deal with fluids. However, for the time being, it is more important to be able to document things at all and add at least some initial documentation. For a lot of functions, this has already been achieved, and with your suggested extensions to the snarfer we will get a further large step ahead. > KN> but I think it is easier for programmers to write C docstrings in > KN> comment style. Although those docstrings cannot be parsed by one > KN> snarf command, we don't want to export C docstrings to Scheme users, > KN> anyway. > > I mean comment-style C docstrings cannot be parsed at the same time > as macro-stype Scheme docstrings. I think this is okay because they > are different concepts. Well, I don't think we should differentiate it here. You are right that the duplication of the macro names is not beautiful, but I'd nevertheless prefer a common handling and a common documentation data base for guile. Assume you are working in emacs on C code for guile or an extension. Then, you would want to be able to get all the documentation, no matter whether for the C or for the scheme level. At least I wouldn't like it if I had to check two different places for documentation. And if we think of a crossref-enabled documentation system, there's a lot of potential here: It would be great if the documentation for null? would also point me to scm_nullp and SCM_NULLP, and all of these would point me to common descriptions of the concept of lists, cells, etc. Best regards Dirk
Index Nav: | [Date Index] [Subject Index] [Author Index] [Thread Index] | |
---|---|---|
Message Nav: | [Date Prev] [Date Next] | [Thread Prev] [Thread Next] |