Documentation syntax

Hi Smalltalk users,

As I'm just beginning, the only thing I can do is test, try and
experiment with it. Another thing I can do is document stuff as I
learn.

I'm hoping to create an online documentation system which can be
exported/spliced into the source when needed and vice-versa. Because
we only have one documentation comment block per function, we need
extra syntax to allow the defenition of arguments etc.

Some of these syntaxes are:
- @-sign (e.g. @return, @arg hello The hello argument)
- \-sign (same but a \ instead of @
- XML
- HTML

Both XML and HTML give to much overhead in my opinion, so those seem stupid.
Furthermore, the \-sign is already an escape character, so that might
also be a problem. However, the @ sign requires the use of the SHIFT
key.

So, any strong/weak opinions either way??


Greetings,
  Bram


_______________________________________________
help-smalltalk mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/help-smalltalk

Bram Neijt wrote:
> Hi Smalltalk users,
>
> I'm hoping to create an online documentation system which can be
> exported/spliced into the source when needed and vice-versa. Because
> we only have one documentation comment block per function, we need
> extra syntax to allow the defenition of arguments etc.

I don't really know what you mean by "an online documentation system",
so I might still be persuaded, but I don't really see the need for the
markup.

Take this method:

PositionableStream >> copyFrom: start to: end
    "Answer the collection on which the receiver is streaming, from
     the start-th item to the end-th"

    ^collection copyFrom: start to: end

Arguably, this comment doesn't tell us anything that isn't self-evident,
but anyway, how would you mark it up so that it gives us more information?

\ isn't an escape character in Smalltalk.

Regards,

Mike


_______________________________________________
help-smalltalk mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/help-smalltalk

I agree that, in general, Smalltalk methods tend to be small enough that
nobody felt the need for markup.  However, I think it would not be bad
to support some kind of markup, especially a very simple one.

For example, some Texinfo commands could be recognized and subject to
special treatment.  For Texinfo, the @ would not be escaped @var{start};
for HTML, a suitable markup could be produced.  For example, the above
could be written as

    "Answer the collection on which the receiver is streaming, from
     the @var{start}-th item to the @var{end}-th"


I believe that this could help the readability of the manual--OTOH it
would hinder the readability of the source code.  Maybe we need a
simpler coding, like

    "Answer the collection on which the receiver is streaming, from the
     @{start}-th item to the @{end}-th.  _@{start} and @{end} are not checked
     to be less than or equal to the stream's position!_"

i.e.  @{XXX} becomes @var{XXX} or <i><tt>XXX</tt></i>, and _abc_ becomes
@emph{XXX} or <strong>XXX</strong> (respectively for Texinfo and HTML).

Paolo



_______________________________________________
help-smalltalk mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/help-smalltalk

Hi Mike and Paolo (and other readers),

I can see why an online documentation system doesn't seem needed. And
the short awnser is: it isn't. Smalltalk was designed to be used while
working in the system, like Squeak (as far as I can see). So all
documentation can be done with a browser/viewer within the virtual
machine.

My logic behind wanting markup was actually driven by my desire to
build a community driven wiki like documentation system for GNU
Smalltalk.

Common documentation systems include things like: examples, verbose
argument explanaition, return value and type explenation, possibly
TODO's, a 'see also' list, links, class variable documentation, etc.

So to awnser the question 'what, if anything, would a markup add?':
one or more of the above (as needs be ;-) ). (Keep in mind that this
didn't start because of a lack of documetation or it's quality: simply
because I would like a wiki system with that same markup.)

On 8/16/06, Paolo Bonzini <[hidden email]> wrote:
> I believe that this could help the readability of the manual--OTOH it
> would hinder the readability of the source code.  Maybe we need a
> simpler coding, like
This is a very valid point, if any markup is chosen it should keep the
code comments readable. However, the markup (just to be clear) is not
ment for things like "emphasis", this was not what I ment. IMHO it
should only point out which parts are special (variable names, class
names) or bind information to an entity (like HTML definition lists
(DL)).

The Javadoc/doxygen method is:
PositionableStream >> copyFrom: start to: end
    "Answer the collection on which the receiver is streaming, from
      the start-th item to the end-th
    @arg start The starting position
    @arg end The ending position
    @see Smalltalk.Collection
    "
     ^collection copyFrom: start to: end

But we have the freedom to choose whatever fits Smalltalk best :-D

Well, that probably raised enough questions/comments.

Thanks for the responses,
  Bram


_______________________________________________
help-smalltalk mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/help-smalltalk

A bit off topic...

I use Squeak a lot, and one of the things that is really lacking in  
Smalltalk documentation methods is the idea of a  package level  
document, not just class and method, which work fine.  One of the  
frustrating things is looking at many, many classes and not having  
any pointers as which class would be used for what purpose, etc. A  
package level doc facility would alleviate this.  I don't know enough  
about gst yet to know if it has such a facility.

My .02

Brian

On Aug 16, 2006, at 11:49 AM, Bram Neijt wrote:



_______________________________________________
help-smalltalk mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/help-smalltalk

Bram Neijt wrote:
> I can see why an online documentation system doesn't seem needed. And
> the short awnser is: it isn't. Smalltalk was designed to be used while
> working in the system, like Squeak (as far as I can see). So all
> documentation can be done with a browser/viewer within the virtual
> machine.

On the contrary: when I first started learning (GNU) Smalltalk, I
referred to the generated HTML docs extensively. In addition, having to
install a package in order to find out anything about it is something I
find very off-putting about other-dialect packages. I'm sure that the
same is true of GSt.

> Common documentation systems include things like: examples, verbose
> argument explanaition, return value and type explenation, possibly
> TODO's, a 'see also' list, links, class variable documentation, etc.
>
> So to awnser the question 'what, if anything, would a markup add?':
> one or more of the above (as needs be ;-) ). (Keep in mind that this
> didn't start because of a lack of documetation or it's quality: simply
> because I would like a wiki system with that same markup.)

It seems to me that all of the additional information that is worth
having is either a link or a link in disguise.

[chopping up the replies - I hope this doesn't offend anybody]

> The Javadoc/doxygen method is:
> PositionableStream >> copyFrom: start to: end
>    "Answer the collection on which the receiver is streaming, from
>      the start-th item to the end-th
>    @arg start The starting position
>    @arg end The ending position
>    @see Smalltalk.Collection
>    "
>     ^collection copyFrom: start to: end

OK, but the method is now five lines of comment and one of code, and
arguably didn't need the two lines of comment that it started with.

What I was getting that was that, if you have "copyFrom: start to: end",
and you also have "from the start-th item to the end-th", what
additional information are you getting from "@arg start The starting
position" and "@arg end The ending position" ?

Also, if "Answer the collection" was written "Answer the Collection",
then Collection could be made into a link without adding any markup.

Mike


_______________________________________________
help-smalltalk mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/help-smalltalk

Mike Anderson wrote: More so, since the browser is not the main development environment
(which is not going to change anytime soon). Yep.  They're only there for the sake of documentation generation, not
because a code reader would need them.
> What I was getting that was that, if you have "copyFrom: start to: end",
> and you also have "from the start-th item to the end-th", what
> additional information are you getting from "@arg start The starting
> position" and "@arg end The ending position" ?
>  
Nothing :-)  But I still think it would add something to have @{start}
and @{end} show up in a different font.  And bonus points if you can get
ASCII "markup" like "_Do not_ do this" into formatting markup.
> Also, if "Answer the collection" was written "Answer the Collection",
> then Collection could be made into a link without adding any markup.
>  
That's true.

Paolo


_______________________________________________
help-smalltalk mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/help-smalltalk

begin  quoting Paolo Bonzini as of Thu, Aug 17, 2006 at 08:52:24AM +0200:
> Mike Anderson wrote:
[snip]
> >On the contrary: when I first started learning (GNU) Smalltalk, I
> >referred to the generated HTML docs extensively. In addition, having to
> >install a package in order to find out anything about it is something I
> >find very off-putting about other-dialect packages. I'm sure that the
> >same is true of GSt.
>
> More so, since the browser is not the main development environment
> (which is not going to change anytime soon).

As many of us rely heavily on the HTML documentation, perhaps we could
look at the deficiences there, and come up with what we'd like in an
automated-document-generator...

Elsethread it was recommended that we have package-level documentation,
which I thing would be pretty useful as well.

A parent- and child-hierarchy and a used-by list would be on my wishlist.

The document writer could put in type hints for the document reader,
as the document reader needs more information than the code reader...

  " ...
  @arg start a {Number} not less than 0 indicating the start position.
  @arg end a {Number} not less than _start_ indicating the end position.
    ..."

(Mabye type-hints? e.g. "@arg Number start ...." -- but that feels
like it would go terribly wrong...)

> >What I was getting that was that, if you have "copyFrom: start to: end",
> >and you also have "from the start-th item to the end-th", what
> >additional information are you getting from "@arg start The starting
> >position" and "@arg end The ending position" ?
>
> Nothing :-)  But I still think it would add something to have @{start}
> and @{end} show up in a different font.  And bonus points if you can get
> ASCII "markup" like "_Do not_ do this" into formatting markup.

Standard usenet (and some wiki) markup rules?  *Strong*, /emphasize/
or _emphasize_, etc.?  Yes, that would be nice.

> >Also, if "Answer the collection" was written "Answer the Collection",
> >then Collection could be made into a link without adding any markup.
>
> That's true.

Markup would be needed to un-select inappropriate links. If I have
a class named "Answer", it shouldn't be linked to everytime someone
writes "Answer the blah-blah-blah", as it would be unrelated, and
the resulting link would be confusing.

--
Stewart Stremler


_______________________________________________
help-smalltalk mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/help-smalltalk

On 8/17/06, Stewart Stremler <[hidden email]> wrote:
> Markup would be needed to un-select inappropriate links. If I have
> a class named "Answer", it shouldn't be linked to everytime someone
> writes "Answer the blah-blah-blah", as it would be unrelated, and
> the resulting link would be confusing.
This is a problem I already noticed. Which would mean some kind of
markup is needed. However, we could still use very simple markup, like
brackets ("[]") to donate that that term is special (which would make
it a link).

I'll just build the first part of a wiki type system and then we can
always change the parsing system.

I'll get back to you all then :-D

Greets,
  Bram


_______________________________________________
help-smalltalk mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/help-smalltalk

Bram Neijt wrote:
It's not a real problem. The potentically problematic words are, in
fact, "Set" and "File" (and one ungrammatical "Error"). If you didn't
make links when the word was the first word in the comments, then
they're all covered.

Mike

Object subclass: 'ThisScript'!

ThisScript methodsFor: 'everything'!

allBaseClasses
        ^Smalltalk select: [ :each | each isClass ]
!

extractComment: aMethodSourceString
        | s c |
        aMethodSourceString isNil ifTrue: [ ^'' ].
        s := aMethodSourceString readStream.
        s upTo: Character nl.
        s skipSeparators.
        s next = $" ifFalse: [ ^'' ].
        c := s upTo: $".
        [ s next = $" ]
                whileTrue:
                [ c := c, '"', s upTo: $" ].
        ^c
!

capsInComment: aComment
        ^aComment isNil
                ifTrue:
                        [ #() ]
                ifFalse:
                        [ aComment subStrings select:
                                [ :each | each first isUppercase ] ].
!

run
        | abc names capitalized |
        capitalized := Set new.
        abc := self allBaseClasses asSortedCollection: [ :a :b | a name < b name ].
        names := abc collect: [ :cls | cls name asString ].
        abc do:
                [ :c |
                c selectors do:
                        [ :s | | comment ms caps |
                        ms := (c >> s) methodSourceString.
                        comment := self extractComment: ms.
                        caps := self capsInComment: comment.
                        capitalized addAll: caps.
                        caps := caps select: [ :each | names includes: each ].
                        caps notEmpty
                                ifTrue:
                                        [ Transcript nl; nl.
                                        Transcript << c name << ' >> '.
                                        Transcript << (c >> s) selector ; nl.
                                        Transcript << comment ; nl.
                                        caps
                                                do:
                                                        [ :cap | Transcript << cap ]
                                                separatedBy:
                                                        [ Transcript << ' ' ]. ]. ] ].
                                                       
        "Transcript << '*** All base classes ***' ; nl.
        abc
                do:
                        [ :cls | Transcript << cls name ]
                separatedBy:
                        [ Transcript << ' ' ].
        Transcript nl.
        Transcript << '*** All caps ***' ; nl.
        capitalized asSortedCollection
                do:
                        [ :cap | Transcript << cap ]
                separatedBy:
                        [ Transcript << ' ' ].
        Transcript nl.
        Transcript << '*** Intersection ***' ; nl.
        (capitalized & (abc collect: [ :each | each name asString ]) asSet)
                do:
                        [ :cap | Transcript << cap ]
                separatedBy:
                        [ Transcript << ' ' ].
        Transcript nl."
!
!

ThisScript new run
!


_______________________________________________
help-smalltalk mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/help-smalltalk

Stewart Stremler wrote:

> Elsethread it was recommended that we have package-level documentation,
> which I thing would be pretty useful as well.

I definitely agree.

> A parent- and child-hierarchy and a used-by list would be on my wishlist.

What is used-by? A reversed pre-requisites? Try the attached. That's
generated from:

        | pkgs usedBy |
        pkgs := PackageLoader packages.
        usedBy := LookupTable new: pkgs size.
        pkgs do: [ :pkg | usedBy at: pkg name put: Set new ].
        pkgs do:
                [ :pkg | pkg prerequisites do:
                        [ :prq | usedBy at: prq ifPresent:
                                [ :set | set add: pkg name ] ] ].

Incidentally, that showed up that DhbNumericalMethods relies on
DhbNumericalMethodsExtensions, which doesn't exist.
I'd say so:

Object >> perform: selectorOrMessageOrMethod

"Send the unary message named selectorOrMessageOrMethod (if a Symbol) to
the receiver, or the message and arguments it identifies (if a Message
or DirectedMessage), or finally execute the method within the receiver
(if a CompiledMethod). ..."

Regards,

Mike

<script type="text/javascript" src="Packages_files/sarissa.bin"> </script><script type="text/javascript" src="Packages_files/browser.bin"> </script><script type="text/javascript"> addEvent(window, 'load', function () { }, false);</script>
"======================================================================
|
| Copyright 2006 Mike Anderson
| Written by Mike Anderson
|
| This file is part of Mumble, a development environment for GNU Smalltalk.
|
| Mumble is free software; you can redistribute it and/or modify it
| under the terms of the GNU General Public License as published by the Free
| Software Foundation; either version 2, or (at your option) any later version.
|
| Mumble is distributed in the hope that it will be useful, but WITHOUT
| ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
| FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
| details.
|
| You should have received a copy of the GNU General Public License along with
| Mumble; see the file COPYING.  If not, write to the Free Software
| Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  
|
 ======================================================================
"

BrowserInitializeResponse subclass: #PackagesInitResponse
!

PackagesInitResponse methodsFor: 'everything'!

selfUrl
        ^'/Browser/Packages'.
!

sendPackageList: aNames heading: aHeading
        self element: 'h4'; text: aHeading; end: 'h4'.
        aNames isEmpty
                ifTrue:
                        [ self element: 'p'; text: 'None'; end: 'p' ]
                ifFalse:
                        [ self element: 'ul'.
                        aNames asSortedCollection do:
                                [ :name |
                                self
                                        element: 'li';
                                        element: 'a';
                                        attribute: 'href' value: '#', name;
                                        text: name;
                                        end: 'a';
                                        end: 'li'. ].
                        self end: 'ul'. ].
!

sendBodyContent
        | pkgs usedBy |
        pkgs := PackageLoader packages.
        usedBy := LookupTable new: pkgs size.
        pkgs do: [ :pkg | usedBy at: pkg name put: Set new ].
        pkgs do:
                [ :pkg | pkg prerequisites do:
                        [ :prq | usedBy at: prq ifPresent:
                                [ :set | set add: pkg name ] ] ].
       
        (pkgs asSortedCollection:
                [ :a :b | a name < b name ])
                do:
                [ :pkg |
                self
                        element: 'div';
                        attribute: 'id' value: pkg name;
                        element: 'h3';
                        text: pkg name;
                        end: 'h3';
                        sendPackageList: pkg prerequisites heading: 'Pre-requisites';
                        sendPackageList: (usedBy at: pkg name) heading: 'Used by';
                        end: 'div'. ].
!

initScript
        ^''
"^'get_and_eval(''', self selfUrl, '?Name=Smalltalk'',
        document.getElementById(''root''));'"
!
!



_______________________________________________
help-smalltalk mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/help-smalltalk