Opened 3 years ago

Closed 3 years ago

#17803 closed enhancement (fixed)

Documentation additions and changes for wxStyledTextCtrl

Reported by: NewPagodi Owned by: Artur Wieczorek <artwik@…>
Priority: normal Milestone:
Component: wxStyledText Version: dev-latest
Keywords: documentation Cc:
Blocked By: Blocking:
Patch: yes

Description

It was requested that #17680 be broken into smaller pieces. This is the second (and final separate) piece.

The patch makes a number of changes to the documentation for wxStyledTextCtrl. The most significant changes are:

  1. adds a table of contents to the documentation for wxSTC.
  2. breaks the brief list of methods into categories corresponding to the table of contents.
  3. deletes 2 methods (StyleSetCharacterSet and PointFromPosition) from the manually declared methods and instead has them be generated by gen_iface.py. This is so that they'll be listed in the category with the scintilla methods.
  4. adds SetUseAntiAliasing and GetUseAntiAliasing to the list of manually declared methods. If there is a reason they weren't listed there already, let me know and I'll remove them.
  5. adds documentation for the wxTextEntry and wxTextArea methods. I wasn't completely sure what to do with these so I just copied the docs from wxTextEntry and wxTextCtrl. There are 3 exceptions: SetStyle, GetStyle, and SetDefaultStyle have implementations like:
wxFAIL_MSG("not implemented");

return false;


I set their doc strings to be: "This method is inherited from wxTextAreaBase but is not implemented in wxStyledTextCtrl." If there's a better way phrase that, let me know and I'll change it.

A sample can be seen here:
https://newpagodi.github.io/tempstcdocs/classwx_styled_text_ctrl4.html
(I cut out most of the event list and scintilla methods to make it easier to see what the category structure looks like.)

other small changes

  1. adds @since annotation to GetTargetTextRaw
  2. slightly changed docstring for SendMsg
  3. I had to move GetLibraryVersionInfo to the end since doxygen stops listing the methods when it hits that one. I'm not sure if that's because all the others are now in a category except for that one or because it's a static method. But with it listed at the end, everything still works.
  4. added wxEVT_STC_AUTOCOMP_COMPLETED and wxEVT_STC_MARGIN_RIGHT_CLICK to the list of events at the end of stc.interface.h.in. I guess I missed adding them to that list when I added those changes to wxSTC.

Other cosmetic changes to stc.interface.h.in

  1. I set all of the method groups to a consistent set of comments at the start.
  2. I set all the methods to have 1 empty line of space between them.

Attachments (1)

stcdocs1.patch download (53.6 KB) - added by NewPagodi 3 years ago.

Download all attachments as: .zip

Change History (4)

comment:1 follow-up: Changed 3 years ago by awi

  • Status changed from new to infoneeded_new

Thanks for this (next) step to improve the documentation!

I have some questions/remarks regarding proposed modifications:

  1. Ref. "deletes 2 methods (StyleSetCharacterSet and PointFromPosition)...": AFAICS, manually declared methods (in stc.h.in) go the one category ("Scintilla methods") and methods generated by gen_iface.py go to the another category ("Additional wxSTC methods") in the documentation. Are there any significant functional differences between these two kinds of methods which would justify introducing this distinction? Is it worth to separate these methods in the documentation?
  1. Ref. "slightly changed docstring for SendMsg":

Implementation of this method looks like this:

wxIntPtr wxStyledTextCtrl::SendMsg(int msg, wxUIntPtr wp, wxIntPtr lp) const
{
    return m_swx->WndProc(msg, wp, lp);
}

So, I am not sure if new description (Send a Scintilla message to the control) is more adequate than the old one (Send a message to Scintilla).
Perhaps compilation of both would be formally fine (Send a Scintilla message to Scintilla) but it sounds really ugly. Any ideas?

comment:2 in reply to: ↑ 1 Changed 3 years ago by NewPagodi

  • Status changed from infoneeded_new to new

Replying to awi:

Thanks for this (next) step to improve the documentation!

I have some questions/remarks regarding proposed modifications:

  1. Ref. "deletes 2 methods (StyleSetCharacterSet and PointFromPosition)...": AFAICS, manually declared methods (in stc.h.in) go the one category ("Scintilla methods") and methods generated by gen_iface.py go to the another category ("Additional wxSTC methods") in the documentation. Are there any significant functional differences between these two kinds of methods which would justify introducing this distinction? Is it worth to separate these methods in the documentation?

At this point I guess there isn't much need for the separation. But if #17680 is accepted, gen_iface.py will be modified to break the generated methods into categories like "Text retrieval and modification" and "Searching and replacing" as in the Scintilla documentation. Then there will have to be a separate category for the manually declared methods. This just creates that category now. If you want, I can delete the category for now and create it when I resubmit #17680.


  1. Ref. "slightly changed docstring for SendMsg":

Implementation of this method looks like this:

wxIntPtr wxStyledTextCtrl::SendMsg(int msg, wxUIntPtr wp, wxIntPtr lp) const
{
    return m_swx->WndProc(msg, wp, lp);
}

So, I am not sure if new description (Send a Scintilla message to the control) is more adequate than the old one (Send a message to Scintilla).
Perhaps compilation of both would be formally fine (Send a Scintilla message to Scintilla) but it sounds really ugly. Any ideas?

It's not a big deal. I've updated the patch to leave the docstring as is.

Changed 3 years ago by NewPagodi

comment:3 Changed 3 years ago by Artur Wieczorek <artwik@…>

  • Owner set to Artur Wieczorek <artwik@…>
  • Resolution set to fixed
  • Status changed from new to closed

In 6bf083857f77d2967997947764cbede1a1ddf35d/git-wxWidgets:

Update wxStyledTextCtrl documentation

Table of contents is added to the documentation for wxSTC and the brief list of methods is broken into categories corresponding to this table. Documentation of several methods is rearranged and edited.

Closes #17803.

Note: See TracTickets for help on using tickets.