[squeak-dev] self error: 'comment only'

tim Rowledge tim at rowledge.org
Sat Mar 21 21:20:10 UTC 2020



> On 2020-03-21, at 12:11 PM, Thiede, Christoph <Christoph.Thiede at student.hpi.uni-potsdam.de> wrote:
> 
> > Actually, javadoc can do a very nice job of generating documentation if someone has taken the time to write good comments in the first place. Not unlike the situation in Squeak.
> 
> I think I don't like documentation generation.

The problem is always, at the end, having some useful content. A level up from that is having said useful content well organised. I'm sure it's possible to make a javadoc thing that assembles stuff, and surely it must be possible to tag it to aid organisation. Does it do that? No idea; I don't go near java.


> . Ideally, we should also never copy documentation stuff into the Swiki, but implement a hook/special syntax there that allows citing it directly from the Swiki server's image.

Yeah, probably. I'm sure we could either parse the html the swiki returns a bit better (after all, we used to have a not too terrible web browser and it's not like the swiki produces complex 'modern' web pages that rely on implausible numbers of poorly written and badly used frameworks residing on a gazillion different sites ... oh, wait, am I ranting again?) or we could possibly make a swiki that provides more easily digestible pseudo-html (or maybe sometihng like markdown, or even, since the swiki is a sort of markup language just the raw text) on suitable request.

Obviously, the main issue is still content. And not all the swiki needs to be handled, after all; just pages that are tagged as part of the help doc system. 


tim
--
tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
Security announcement - as of next week, passwords will be entered in Morse code.




More information about the Squeak-dev mailing list