#1556 Scintilla.iface - feature vs. pure comments

Bug
closed-rejected
Neil Hodgson
scintilla (127)
5
2013-11-26
2013-11-21
green9
No

This report is about lines denoted as documentation comments (prefixed with "# ")
which should actually be file comments (prefixed with "##").

I do realize that reporting this might seem rather picky, so here is the point:

The interface file can be parsed and contains a documentation comment for almost
every feature. In short, you could parse the interface file, generate some dummy
code and then use some tool like NDoc or Sandcastle Builder to produce some
documentation for it.

I hopefully managed to add a screenshot to this report. This should give you
some first impression of a possible result.

At this point it should be obvious that a parser can't prevent these non-documentation
comments from appearing in the generated documentation files. So the following
lines should be prefixed with another "#".

246: # Shapes used for outlining column.
261: # Invisible mark that only sets the line background colour.
275: # Markers used for outlining column.
1498+: # These are like their namesakes Home(Extend) ...
1660: # Constants for use with SetVisiblePolicy
2416: # Notifications
unclear => looks like some kind of a "group header"
2449+: # For compatibility, these go through the ...
2457+: # Symbolic key codes and modifier flags.
2492: # For SciLexer.h
2720: # XML and ASP
2729: # More HTML
2731: # X-Code
2733: # SGML
2745: # Embedded Javascript
2759: # ASP Javascript
2773: # Embedded VBScript
2782: # ASP VBScript
2791: # Embedded Python
2805: # PHP
2807: # ASP Python
2821: # PHP
4384: # Events
4391: # GTK+ Specific to work around focus and accelerator problems
unclear => refers to the Key-event only?

1684: # Caret policy, used by SetXCaretPolicy ...
- seems to be a documentation comment for "enu CaretPolicy"
- move the comment up one line

4473: # Deprecated in 2.30
- documentation comments relate to the succeeding feature only
- copy and paste to SetUsePalette

These were only those lines that caught my eye. There might be more...

1 Attachments

Discussion

  • Neil Hodgson
    Neil Hodgson
    2013-11-22

    It seems reasonable for a transformation to include these in the output as comments unlike the file format comments that use ##.

     
    • green9
      green9
      2013-11-22

      Take "# Events" for example. This comment is clearly used as a group header with the meaning that all the following procedures are event procedures. So you introduce some implicit ordering: first the group header, then the event procedures with no particular order.

      But as it is defined, "# Events" has to be interpreted as documentation comment for "StyleNeeded". Thus, this implicit ordering/grouping info is lost when you use a transformation. That is because documented features will automatically be sorted alphabetically.

      This particular case could be transformed into an "Events" category. The issue with many others is similar although you won't want to change them into their own categories.

      To summarise this: If you wanted to keep this implicit ordering/grouping, you might want to think about introducing a new directive. Something like C#'s "#region <name>" and "#endregion" delimiters.

       
      • Neil Hodgson
        Neil Hodgson
        2013-11-26

        I don't think there is a bug here.

        There could be a feature request but it's not presented in a manner that is simple to implement.

         
        • green9
          green9
          2013-11-26

          The reason I posted this as a bug report is because I considered the above lines to have typos; "# " instead of "##". But if you don't want to change them, then I consider this case closed.

           
  • Neil Hodgson
    Neil Hodgson
    2013-11-26

    • labels: --> scintilla
    • status: open --> closed-rejected
    • assigned_to: Neil Hodgson
     
  • Neil Hodgson
    Neil Hodgson
    2013-11-26

    OK, closed.