HelpSystem & Class comments
Locked
 
|
Hi -
I'd like to add a feature request to HelpSystem: Adding a very simple pattern that can be used to provide structure in class comments, perhaps along the lines of Wiki syntax. Why would that be good? Several reasons: a) Currently a book depends on the presence of HelpSystem (i.e., via subclassing). This needs to be fixed - we need to be able to have documentation in the system without necessarily requiring a viewer. b) Typing in '' quotes is pretty insane when you quote text. The constant use of it''s instead of it's etc. is VERY distracting. Code examples look like crap etc. In the class comment you can write straight away. c) Class comments are WYSIWIG for the purposes of HelpSystem. One can create links, doIts, highlights and see the effects right away. This isn't easily possible otherwise since we don't have literal text syntax. d) It's the right place for documentation anyway. I'm not saying that comments are the only way by which HelpBooks should be created but I think that this should be one of the ways that HelpSystem directly supports. In fact what happened was that I was trying to use HelpSystem and ended up to move all the docs into the class comment for all of the above reasons. For example, we could just say that we define a help book marker and a topic boundary and then your class comment looks like here: This is a sample class comment. [HelpBook: 'MyClass Introduction'] Anything you see here will be displayed as the abstract for the help book. === MyClass Introduction This is an introduction to MyClass. You can read about its most interesting feature. === MyClass Frobnification Frobnification, the process of frobnifiying a snuzzle, is the main purpose of MyClass. [HelpBook: 'MyClass Reference'] === frobnify: aSnuzzle This is the main interface to MyClass. It takes a Snuzzle and frobnifies it. Note that there is some discussion about whether the result is a fronbnified or a frobnificated snuzzle. Example: MyClass new frobnify: RectangularSnuzzle new. Etc. The point being that it's easy to edit, you get both a class comment and a book out of it, and people looking at it will say "holy cow! i guess there *is* some documentation somewhere here :-)" I'd be happy to help you with this if you think it's worthwhile. Cheers, - Andreas |
|
|
In Sake we have a special Compiler Hack called SakeCompiler.
This uses """""" (6 quotes) to mark the end of the method, from then on you can put any content you like in the method. There are accessors docAt: selector Keith |
|
|
On 24 Feb 2010, at 01:57, keith wrote:
Not forgetting of course that you can mark documentation methods with a pragma. I could be wrong but I think that the the #compilerClass call only works for overriding instance side method behaviour, the hack would have to be more universal (or attached to MetaClass >> compilerClass ) for other methods. Ok it is hacky, but it is "very" useful. If you have a better idea, which I am sure you do I am all ears. Keith |
|
|
keith wrote:
> Not forgetting of course that you can mark documentation methods with a > pragma. > I could be wrong but I think that the the #compilerClass call only works > for overriding instance side method behaviour, > the hack would have to be more universal (or attached to MetaClass >> > compilerClass ) for other methods. > > Ok it is hacky, but it is "very" useful. If you have a better idea, > which I am sure you do I am all ears. This is definitely useful although I'd like to think a little bit harder about the syntax to choose. However, for the purpose of writing documentation for a class or subsystem I'd still say that a class comment is a great place to put it :-) Cheers, - Andreas |
Re: HelpSystem & Class comments
|
|
In reply to this post by keith1y
On Tue, Feb 23, 2010 at 5:57 PM, keith <[hidden email]> wrote: In Sake we have a special Compiler Hack called SakeCompiler. Using a pragma is a better way. The pragma can include any number of strings, and literal strings can^H^H^Hshould be able to contain any characters. One can add additional keywords top define additional metadata. There is already a protocol for accessing pragmas and arguments from methods. One can have multiple pragmas, etc. If the pragma is well-designed one can perform the pragma to output the documentation. i.e. the pragma message is also understood by a formatter/generator, and so by browsing implementors of the pragma you get immediately to the code that can process said pragma. There's a wrinkle in that the generator needs to be parameterised by the class and selector of the method before it performs the pragma, but that aside, it is quite neat.
e.g. Documentor new outputTo: aStream; documentFrom: aSubClass to: aSuperClass documentFrom: aSubClass to: aSuperClass
(Pragma allNamed: self documentationPragma from: aSubClass to: aSuperClass) do: [:p| currentClass := p class. currentSelector := p selector. p message sendTo: self]
|
|
|
In reply to this post by Andreas.Raab
We had/have the text of the whole of Mantis exported into Methods, for reading/searching in the image. Keith |
|
|
In reply to this post by Andreas.Raab
Might I suggest a close look at Donald E. Knuth's Literate Programming, and WEB, CWEB, etc.
Donald E. Knuth's home page: <http://www-cs-faculty.stanford.edu/~uno/index.html> The CWEB System of Structured Documentation <http://www-cs-faculty.stanford.edu/~uno/cweb.html> Daniel Mall's website for Literate Programming <http://www.literateprogramming.com/> Ken G. Brown At 5:18 PM -0800 2/23/10, Andreas Raab apparently wrote: >Hi - > >I'd like to add a feature request to HelpSystem: Adding a very simple pattern that can be used to provide structure in class comments, perhaps along the lines of Wiki syntax. Why would that be good? Several reasons: > >a) Currently a book depends on the presence of HelpSystem (i.e., via subclassing). This needs to be fixed - we need to be able to have documentation in the system without necessarily requiring a viewer. > >b) Typing in '' quotes is pretty insane when you quote text. The constant use of it''s instead of it's etc. is VERY distracting. Code examples look like crap etc. In the class comment you can write straight away. > >c) Class comments are WYSIWIG for the purposes of HelpSystem. One can create links, doIts, highlights and see the effects right away. This isn't easily possible otherwise since we don't have literal text syntax. > >d) It's the right place for documentation anyway. > >I'm not saying that comments are the only way by which HelpBooks should be created but I think that this should be one of the ways that HelpSystem directly supports. In fact what happened was that I was trying to use HelpSystem and ended up to move all the docs into the class comment for all of the above reasons. > > >For example, we could just say that we define a help book marker and a topic boundary and then your class comment looks like here: > >This is a sample class comment. > >[HelpBook: 'MyClass Introduction'] > >Anything you see here will be displayed as the abstract for the help book. > >=== MyClass Introduction > >This is an introduction to MyClass. You can read about its most interesting feature. > >=== MyClass Frobnification > >Frobnification, the process of frobnifiying a snuzzle, is the main purpose of MyClass. > >[HelpBook: 'MyClass Reference'] > >=== frobnify: aSnuzzle > >This is the main interface to MyClass. It takes a Snuzzle and frobnifies it. Note that there is some discussion about whether the result is a fronbnified or a frobnificated snuzzle. > >Example: > > MyClass new frobnify: RectangularSnuzzle new. > > >Etc. The point being that it's easy to edit, you get both a class comment and a book out of it, and people looking at it will say "holy cow! i guess there *is* some documentation somewhere here :-)" > >I'd be happy to help you with this if you think it's worthwhile. > >Cheers, > - Andreas |
|
|
In reply to this post by Eliot Miranda-2
Sorry but I didnt understand much of this. All I really know about pragma's is that you can put
<blah: #symbol> at the top of some code. Where do you put the documentation in this scheme? Keith
|
|
|
In reply to this post by Andreas.Raab
Hi!
I've added something along this line in the current baseline. In a documentation method of one of your CustomHelp subclasses you return a subclass of DynamicHelpPage. This allows you to create a whole subtree of documentation dynamically. I would like to use the static CustomHelp hierarchy for categorizing, overview documentation for packages, and anything that comes into mind that does not fit nicely into code comments. As an example, the "Help on Help" topic now has API documentation generated automatically from the source. In the Pharo mailing list the idea has come up to use pragmas (<help>) to categorize the methods you are documenting. A preliminary scetch of how this might be done is included. Have a look at the DynamicHelpPage subclasses and feel free to add something more powerful - I am just starting with Smalltalk and seeing what experienced people add or change in my code is teaching me alot. > c) Class comments are WYSIWIG for the purposes of HelpSystem. One can > create links, doIts, highlights and see the effects right away. This > isn't easily possible otherwise since we don't have literal text syntax. How can links and highlights be created? Is this a feature specific to the particular class browser that is used? Danny |
Re: HelpSystem & Class comments
|
|
In reply to this post by keith1y
On 24 February 2010 06:25, keith <[hidden email]> wrote:
> Sorry but I didnt understand much of this. All I really know about pragma's > is that you can put > <blah: #symbol> > at the top of some code. Where do you put the documentation in this scheme? < documentation: ' blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah '> > Keith > > > On Tue, Feb 23, 2010 at 5:57 PM, keith <[hidden email]> wrote: >> >> In Sake we have a special Compiler Hack called SakeCompiler. >> >> This uses """""" (6 quotes) to mark the end of the method, from then on >> you can put any content you like in the method. >> >> There are accessors docAt: selector > > Using a pragma is a better way. The pragma can include any number of > strings, and literal strings can^H^H^Hshould be able to contain any > characters. One can add additional keywords top define additional metadata. > There is already a protocol for accessing pragmas and arguments from > methods. One can have multiple pragmas, etc. If the pragma is > well-designed one can perform the pragma to output the documentation. i.e. > the pragma message is also understood by a formatter/generator, and so by > browsing implementors of the pragma you get immediately to the code that can > process said pragma. There's a wrinkle in that the generator needs to be > parameterised by the class and selector of the method before it performs the > pragma, but that aside, it is quite neat. > e.g. > Documentor new > outputTo: aStream; > documentFrom: aSubClass to: aSuperClass > documentFrom: aSubClass to: aSuperClass > (Pragma allNamed: self documentationPragma from: aSubClass to: > aSuperClass) do: > [:p| > currentClass := p class. > currentSelector := p selector. > p message sendTo: self] > > >> >> Keith >> > > > > > > > -- Best regards, Igor Stasenko AKA sig. |
Re: HelpSystem & Class comments
|
|
In reply to this post by Andreas.Raab
On 24.02.2010, at 02:18, Andreas Raab wrote:
> > Hi - > > I'd like to add a feature request to HelpSystem: Adding a very simple pattern that can be used to provide structure in class comments, perhaps along the lines of Wiki syntax. Has anyone ever looked at SqueakDoc? http://source.impara.de/squeakdoc/ I haven't in ages, but maybe its source-code conventions (modeled along JavaDoc IIRC) could be useful. - Bert - |
Re: HelpSystem & Class comments
|
|
In reply to this post by keith1y
On Tue, Feb 23, 2010 at 8:25 PM, keith <[hidden email]> wrote:
You can inevnt any selector you want, with multiple arguments. So you could choose e.g. myMethod <documentation: 'This method does blah'
author: 'me' apiType: #deprecated> self doStuffInADeprecatedWay Somewhere else, e.g. in your documentation generator you could implement the #documentation:author:apiType: method, e.g.
documentation: docString author: authorString apiType: typeSymbol "Generate doc on outputStream if typeSymbol is a member of the current doc type set." ... The advantage of this is that the pragma has a specification given by the implementation of #documentation:author:apiType:. So unlike the 6 "'s hack, the link between the metadata and what consumes it is explicit, and senders and implementors will find producers (methods carrying the pragma) and consumers (implementors of the pragma).
You then use standard Pragma class-side glue to hook the two up. You might later add a more or less sophisticated pragma to your generator, e.g. DocGenerator methods for documentation pragmas documentation: docString author: authorString apiType: typeSymbol seeAlso: aSequenceOfSelectors "Generate doc on outputStream if typeSymbol is a member of the current doc type set."
When a user browses DocGenerator they'll see all the pragmas and be able to find all uses, be able to add their own etc. Yes one can use pragmas simply as annotations. But I think it's much more powerful when you design pragma selectors that can be implemented, because a) the consumer of the pragma can be found, not puzzled out, b) it's extensible in a reasonably obvious manner by adding more selectors to pragma consumers and c) one can relate multiple consumers (e.g. above a web doc producer or a e.g. browser that displays api overview along with a class definition) by using the same selector to consume pragmas in different generators.
HTH
|
|
|
I use this approach in System-Exports - It has taken me 4 years to find a use for pragmas!
Ah, but since the pragma knows which method it is defined in it can get its documentation from the first code comment, or by invoking the method. In System-Exports I do something like this... "this is the documentation here" <package: 'System-Exports' version: '1.0'> Then package:version: calls self thePragmaClass firstCommentAt: self thePragmaSelector. Or with the """""" scheme. self thePragmaClass docAt: self thePragmaSelector. Using this scheme, every method can be the equivalent of a class comment, AND you can use pragmas to tag, collates and index your documentation.
#> Export slices explore. finds all pragmas that AnnotatedExportSlice understands.
Agreed
I have two types of pragma, the first which picks the processing class, e.g. <package: 'MyPackage version: '1.0'> and the rest are just fed into a keyword/value dictionary. <project: 'MyProject' author: 'kph' item: 7> becomes #project: -> 'MyProject, #author: -> 'kph' #item -> 7. Is it just me or is searching for pragmas in the whole system painfully slow? Is there any good reason not to do, Pragma allInstancesDo: ?
thanks for the detailed explanation Keith |
«
Return to Squeak - Dev
|
1 view|%1 views
| Free forum by Nabble | Edit this page |