search

dolphinsmalltalk / Dolphin

Dolphin Smalltalk Core Image
MIT License
301 stars 58 forks source link

[Doc] regeneration of automatic comments in source files on disk #1141

Closed brickviking closed 8 months ago

brickviking commented 3 years ago

Recently, a suggestion was made to correct comment formatting for auto-generated comments referring to libraries. OS.COM.TKindModuleAnalyzer>>printClassCommentPreambleOn: was the place to make those changes, but all the other autogenerated comments still need correcting in the remainder of the .cls and pax files that have those comments. How do those comments get generated by the image and filed out?

This is an example of one of those badly formatted comments (missing space between DLL name and next sentence) in Core/Object Arts/Dolphin/Sockets/OS.IPHlpApiLibrary.cls:10:

... to represent the dynamic link library, ''iphlpapi.DLL''.It was generated from ...

I have an upcoming fix to add the missing space in the related method, but this doesn't address the comments in the on-disk files.

Do I simply generate a new image from Boot? That will merely fileIn all the files as they exist now, bad formatting and all. Or, do I stick a new stanza somewhere in boot.st or even PreBoot.st, hoping that it will modify the comments on the fly? In that case, how will all the new *.cls/pax files get written out?

I hope I've explained myself adequately.

blairmcg commented 3 years ago

They wouldn't be updated unless somebody re-ran the generation from the type lib. This doesn't happen automatically. The point of the review comment was that if you just manually edited the comments, that your fix would be destroyed by any subsequent re-generation if you didn't also fix the generation code. To apply the change, you would either need to re-run the generation (which in some cases may not be easy as the TLB may not be available, and in others will generate different results because the TLB may have changed), or manually fix them (or more likely script some sort of global replace). Since you have prepared a fix to the code, your edits will not be lost later.