View Issue Details

IDProjectCategoryView StatusLast Update
0001470ScribusInternalpublic2013-09-25 18:45
ReporterringercAssigned Tocbradney  
PrioritylowSeverityfeatureReproducibilityalways
Status closedResolutionwon't fix 
Platformx86 LinuxOSFedora CoreOS Version1
Product Version1.3.0cvs 
Summary0001470: Comments on all classes and members in header files
DescriptionIt'd be very helpful for people who want to contribute to scribus, but don't have the time to learn the whole codebase, if the headers contained more comments describing what the classes and members are for.

In particular, having descriptions of what each variable is would be immensely helpful. If the comments were doxygen compatible, that'd be even better.

Even this basic level of API documentation would make it massively more practical for casual contributors to fix bugs and submit minor enhancements.
Additional InformationI'd volunteer, since I don't mind doing documentation, but I struggle to figure out what most of the variables mean and wrong documentation is worse than no documentation.

For bonus points, comments on the declaration of internal variables on functions just describing very briefly what they are would make the code MASSIVELY more readable:

int flm;

vs

int flm; // distance of left edge from left margin

TagsNo tags attached.
Patch

Relationships

related to 0002376 closedringerc Source code requests 
child of 0002382 acknowledged Metabug: Code quality, structure, readability 

Activities

cniehaus

2004-12-29 14:01

reporter   ~0003284

Well: This should even be a doxygen-style command so that doxygen can add that variable in the documentation.

int flm;
 
 vs
 
int flm; // distance of left edge from left margin

 vs

///distance of left edge from left margin
int flm;

Tsoots

2004-12-30 17:16

reporter   ~0003299

More than documentation I've been missing clear code that would be clean enough to make itself clear. For example my opinion is that a variable should have such a name that it would tell what's it used for.

ringerc

2005-01-18 06:07

reporter   ~0003498

IMO a priority here is to get some Doxygen commments on the members of PageItem in pageitem.h . That'd make it more practical to start sorting them out and building getter/setter slots and properties for them.

ringerc

2005-02-04 05:03

reporter   ~0003612

We're slowly getting there on pageitem.h as part of Tsoots' undo work and some member privacy conversion cleanups I'm doing. The best news is that most of the new names are largely self-explanatory anyway.

Issue History

Date Modified Username Field Change
2004-12-29 12:41 ringerc New Issue
2004-12-29 14:01 cniehaus Note Added: 0003284
2004-12-30 17:16 Tsoots Note Added: 0003299
2005-01-18 06:07 ringerc Note Added: 0003498
2005-02-04 05:03 ringerc Note Added: 0003612
2005-08-03 15:43 ringerc Relationship added related to 0002376
2005-08-03 15:43 ringerc Status new => acknowledged
2005-08-03 16:26 ringerc Relationship added child of 0002382
2013-09-25 18:45 cbradney Status acknowledged => closed
2013-09-25 18:45 cbradney Assigned To => cbradney
2013-09-25 18:45 cbradney Resolution open => won't fix