Bug in Propeller tool software with the Documentation

TheDarkWraith

If you have something like the following:

PUB Test1
''this test does x
...


PRI Test2
''this test does x
...


PRI Test3
''this test does x
...


PUB Test4
''this test does x
...


And you switch to Documentation view the documentation comments for the first PUB block are shown and all the documentation comments for the PRI blocks that follow it appear in the first PUB block until the next PUB block is encountered. It appears the app doesn't stop 'adding' documentation comments until it reaches another PUB block

ksltd

Exactly right - Documentation view shows the documentation to the clients of the object, not the implementors of it.

Phil Pilgrim (PhiPi)

ksltd wrote:

Exactly right - Documentation view shows the documentation to the clients of the object, not the implementors of it.

Not so. If that were the case, the comments for the private methods would not be shown at all. The OP is correct, and I have verified it: there does appear to be a bug in the doc view, since the comments for private methods do appear with their immediately-preceding public methods. Typically, all the private methods would be written after the public methods, in which case such a bug would be less apparent.

-Phil

kuroneko

I don't think we should overcomplicate this. Double quotes apostrophes (line comment) do, single quotes apostrophes don't show up in documentation view. IOW, if you don't want it to be seen then style it accordingly.

Phil Pilgrim (PhiPi)

I guess the solution is just to use single quotes in PRIvate methods, so the comments don't show up in the wrong place (i.e. don't show up at all).

-Phil

TheDarkWraith

I was using double apostrophes not single quotes

kuroneko

TheDarkWraith wrote: »

I was using double apostrophes not single quotes

Apologies, I meant apostrophes where I said quotes. Anyway, the point is that if you don't want comments to show up don't use double apostrophes, single ones will do just fine.

Jeff Martin

Hi,

It's hard for us to classify this as a bug... it's pretty much a feature but with this unintended side effect. Doc comments were not intended to be tied solely to methods, but were intended to show up in documentation view (as opposed to code comments) regardless of where they are in the source. In practice, it was intended that people don't write doc comments for anything they don't intend to be displayed in documentation view.

But the case can be made that we should probably make this exception and just ignore doc comments inside of private methods.

Here's my test code:

PUB A
 'PUB A Code Comment (single line)
 ''PUB A Doc Comment (single line)
 {PUB A Code Comment (multi-line)}
 {{PUB A Doc Comment (multi-line)}}

PUB B
 'PUB B Code Comment (single line)
 ''PUB B Doc Comment (single line)
 {PUB B Code Comment (multi-line)}
 {{PUB B Doc Comment (multi-line)}}

PRI C
 'PRI C Code Comment (single line)
 ''PRI C Doc Comment (single line)
 {PRI C Code Comment (multi-line)}
 {{PRI C Doc Comment (multi-line)}}

PRI D
 'PRI D Code Comment (single line)
 ''PRI D Doc Comment (single line)
 {PRI D Code Comment (multi-line)}
 {{PRI D Doc Comment (multi-line)}}

PUB E
 'PUB E Code Comment (single line)
 ''PUB E Doc Comment (single line)
 {PUB E Code Comment (multi-line)}
 {{PUB E Doc Comment (multi-line)}}

and here's my output (documentation view):

Object "Untitled1" Interface:

PUB  A
PUB  B
PUB  E

Program:       8 Longs
Variable:      0 Longs

______
PUB  A

PUB A Doc Comment (single line)
PUB A Doc Comment (multi-line)
______
PUB  B

PUB B Doc Comment (single line)
PUB B Doc Comment (multi-line)PRI C Doc Comment (single line)
PRI C Doc Comment (multi-line)PRI D Doc Comment (single line)
PRI D Doc Comment (multi-line)
______
PUB  E

PUB E Doc Comment (single line)
PUB E Doc Comment (multi-line)

This test reveals another problem... there's no new line after a multi-line comment being inserted into documentation view.