Refactoring in rst.el (was: Re: [Emacs-diffs] master 9ed3685a77: Lots of refactorings and a few minor improvements.)

[Stefan Merten]

Hi Paul!

3 days ago Paul Eggert wrote:
> Stefan Merten wrote:
>> I got the impression, that lately few people care about these rules
> 
> I'm afraid that impression is incorrect. Many developers care (hence
> this thread :-).

Thanks for reassuring. As you can see in the log I once did care but
this time thought it is no longer worth the hassle.

>> I hope the commit message below is what you require.
> 
> Much better, thanks. My main problem with it is that "Refactor by
> removing old functions, introducing new functions and change existing
> functions" is too vague. Please write for an audience that includes
> people who have code that calls (say) rst-comment-region and want to
> know how to adjust the code after your changes to the API.

Which raises the question what the API of `rst.el` is. So far I was
convinced that nobody will use any function from `rst.el` - so I'd
think that nobody is impacted by refactoring even if I change
signatures of functions. Of course I may be wrong.

Apart from that I'd think the interactive functions are the *real*
interface of `rst.el` which is interesting. Refactoring, however, by
definition does not impact this behavior. Debugging and those minor
changes in behavior which I did during refactoring I did document,
however. Where key bindings are impacted I defined aliases for renamed
functions so older key bindings should continue to work.

In other languages you have this public / private concept. I remember
that in Emacs you started using a double dash in identifiers to mark
them private. For example

        rst-comment-region

would be part of the public interface, while

        rst--comment-region

would be an internal function not meant for public use.

Is that correct? Are the examples valid?

If so, I'd probably like to mark internal functions this way. That
would be a good idea IMHO.


                                                Grüße

                                                Stefan