Issue 3523 in pharo: Nested comments

Status: Accepted
Owner: aplantec

New issue 3523 by aplantec: Nested comments
http://code.google.com/p/pharo/issues/detail?id=3523

Now let me open a big can of worms but we truly need it.
When you write documentation (I did several experiments with Soup) the  
documentation in class comment is cool because you to not have to have
" and " and '' ' ' '' '" everytimes you manipulate a string or a comment.
Now you do not want to have huge class comments I would prefer to have a  
couple of methods and it does not work: you put back the crappy unnestable "
ugly boring.... better not putting comments.

So I would really like to have
        */ this is a nice nestable comment

                "hkjkhhkjh "
                'hkjjkh'
                1 + 2

                        */yet another comment: increbile this is a nested ones: yes you know
                        Smalltalkers are discovering the world/*

                        /*
               
As you see stealing the C comment syntax is a plus because everybody knows  
it.
I remember a discussion on VW about possible syntax to support that.
Before replying to this point thing hard because we need that support.

Updates:
        Cc: renggli

Comment #1 on issue 3523 by aplantec: Nested comments
http://code.google.com/p/pharo/issues/detail?id=3523

Why don't we integrate petitparser in the core ?
Its small and very powerful.
I should make it possible such improvements no ?

Comment #2 on issue 3523 by stephane.ducasse: Nested comments
http://code.google.com/p/pharo/issues/detail?id=3523

Would love but not enough time
      - we want opal, FS....
      + better tools.

Updates:
        Cc: stephane.ducasse

Comment #3 on issue 3523 by [hidden email]: Nested comments
http://code.google.com/p/pharo/issues/detail?id=3523

I think your problem comes from writing the documentation
in the usual tools like class browser, etc. where you edit
a string (with all the '' escaping)

Maybe you should use the EDIT SUPPORT of help system.
Example:

   1. Create a simple subclass of CustomHelp for a new
      book.

        CustomHelp
                subclass: #MyHelpBook
       
                instanceVariableNames: ''
       
                classVariableNames: ''
       
                poolDictionaries: ''
       
                category: 'MyApp-Help'

   2. Implement a class side method to name the book:

        bookName
       
            ^'Help for MyApp'

   3. Now edit page you want by evaluating

        MyHelpBook edit: #page1

      => this opens a new workspace where you can
         write your documentation similar to class
         comments. If you change the title of the window
         you will give your page a name.
      => If you accept the contents of this workspace
         it will be saved in the method #page1

   4. Implement the method to return the books pages:

        pages
       
          ^#(page1)

You dont have to fight with string escaping then

Comment #4 on issue 3523 by stephane.ducasse: Nested comments
http://code.google.com/p/pharo/issues/detail?id=3523

What I described probably but this is a more general problem.
And I hate having all these " around.

Comment #5 on issue 3523 by renggli: Nested comments
http://code.google.com/p/pharo/issues/detail?id=3523

Fist of all, C/C++/Java/C#/JavaScript comments go like this:

     /* some comment */

In any case, introducing that into Smalltalk doesn't work because both #/*  
and #/* are valid binary selectors and it would be highly ambiguous to  
parse something like this:

    12 /* some comment */ a

A combination with the double-quotes $" could work and would avoid the  
ambiguity:

    "* some comment "* some nesting *" *"

Otherwise, I am afraid there is no other character to introduce nested  
comments.

I hope this does look like nitpicking, but C comments are /* */ not */ /*

HTH

--
Cesar Rabak
 



Em 10/01/2011 05:23, [hidden email] escreveu:
Status: Accepted
Owner: aplantec

New issue 3523 by aplantec: Nested comments
http://code.google.com/p/pharo/issues/detail?id=3523

Now let me open a big can of worms but we truly need it.
When you write documentation (I did several experiments with Soup) the  
documentation in class comment is cool because you to not have to have
" and " and '' ' ' '' '" everytimes you manipulate a string or a comment.
Now you do not want to have huge class comments I would prefer to have a  
couple of methods and it does not work: you put back the crappy unnestable "
ugly boring.... better not putting comments.

So I would really like to have
 */ this is a nice nestable comment

 "hkjkhhkjh "
 'hkjjkh'
 1 + 2

 */yet another comment: increbile this is a nested ones: yes you know
 Smalltalkers are discovering the world/*

 /*
 
As you see stealing the C comment syntax is a plus because everybody knows  
it.
I remember a discussion on VW about possible syntax to support that.
Before replying to this point thing hard because we need that support.

Comment #6 on issue 3523 by stephane.ducasse: Nested comments
http://code.google.com/p/pharo/issues/detail?id=3523

I was sure somebody would find the problem :). There was a lng thread a  
while ago in VW about that but now
"*    *" looks good to me because this is just a comment so :)