I have made a first attempt to add docstrings to functions and sent it as a merge request. Maybe some of my comments can be picked. Unfortunately, only commenting the public interface turned out to be harder than I expected, (although it should have been more evident), because the public interface is dependent on the internals, so I had to first understand those.
I have one more meaningful question. In the geiser-base.el, there is a function geiser--del-dups, which is currently working in O(n^2), since is toes a dolist (O(n)) times member (O(n)). Is there an easy way to, maybe, do it in O(nlogn)? Like a hashset, or something like this. вт, 20 нояб. 2018 г. в 20:12, Jose A. Ortega Ruiz <[email protected]>: > > On Tue, Nov 20 2018, Vladimir Nikishkin wrote: > > > What do you think about Emacs's nitpicks, such as 'You should have a > > section marked ;;;Commentary:' or 'all variables and subroutines might > > as well have a documentation string'. > > I usually like nitpicking, and i like the above with a caveat: not all > but only those that are public (in geiser's code base, they're easy to > distinguish, since all non-public names contain a double dash, --). > > > As I am very new to geiser (I actually wanted to learn elisp and > > scheme, but as we all know, the best learning is by doing.), I > > intended to read through the code and mark explanations for myself, > > but I may as well format them as docstrings, for everyone to use. > > That would be a very welcome contribution! > > > On the other hand, also since I am a newbie, there is a high > > likelihood that I misunderstand something, or that these comments > > would potentially clutter the code. > > Here we can collaborate: if you send the additions as merge requests to > GitLab, i'll review them and provide feedback, so that we make sure > we're not being confusing. > > I would limit ourselves at first to docstrings of the public interface > (as mentioned above, there's the double-dash naming convention), as > opposed to internal comments on "how" it works, but if you study the > code and find some implementation detail or idea worth exposing, > comments can be added to the HACKING file (we could eventually create a > chapter in the texi docs for it). And of course i'll be happy to answer > any questions during the process (maybe we could copy geiser-users@ for > them too). > > Cheers, > jao > -- > Come to think of it, there are already a million monkeys on a million > typewriters, and Usenet is NOTHING like Shakespeare. - Blair Houghton. -- Yours sincerely, Vladimir Nikishkin
