STR #1662

FLTK matrix user chat room
(using Element browser app)   FLTK gitter user chat room   GitHub FLTK Project   FLTK News RSS Feed  
  FLTK Apps      FLTK Library      Forums      Links     Login 
 Home  |  Articles & FAQs  |  Bugs & Features  |  Documentation  |  Download  |  Screenshots  ]
 

Return to Bugs & Features | Roadmap 2.0 | Post Text | Post File | SVN ⇄ GIT ]

STR #1662

Application:FLTK Library
Status:5 - New
Priority:2 - Low, e.g. a documentation error or undocumented side-effect
Scope:3 - Applies to all machines and operating systems
Subsystem:Unassigned
Summary:FLTK API docs: request for standard documenting of pointer return values
Version:2.0-current
Created By:greg.ercolano
Assigned To:Unassigned
Fix Version:Unassigned
Update Notification:

Receive EMails Don't Receive EMails

Trouble Report Files:

Post File ]

No files


Trouble Report Comments:

Post Text ]
Name/Time/Date Text top right image
 
#1 greg.ercolano
15:20 Apr 27, 2007
Any funcs/methods that return a pointer should have a standard indication of memory implications:

    o Whether the data needs to be freed or not (new or delete)

    o Whether the data is static or not (affects threading)

The latter underlining a distinction between static data and dynamically allocated data internally managed by the class; though both don't concern the caller for free()ing/delete()ing, there is still a distinction between the two, as static data is potentially dangerous to a threaded app.

Currently some docs seem to not be clear on this, eg:
http://fltk.org/doc-2.0/html/structFont.html#m2

It would be good if the 'return value' is documented in such a way that it's easy for an app programmer to find (eg. the last sentence in the docs for the function, or a separate 'Return Value' section, similar to unix manpages) and the language consistent regarding static vs non-static, and whether the data needs to be freed with free() or delete().

This applies to both FLTK 1.x and 2.x.

This is probably a request to modify the CMP to include these specifics under the "Documenting Functions and Methods" section.
 
bottom left image   bottom right image

Return to Bugs & Features | Post Text | Post File ]

 
 

Comments are owned by the poster. All other content is copyright 1998-2024 by Bill Spitzak and others. This project is hosted by The FLTK Team. Please report site problems to 'erco@seriss.com'.