[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-devel
Subject:    Re: Internal documentation patches
From:       Gordon Sadler <gbsadler1 () lcisp ! com>
Date:       2001-03-07 20:50:12
[Download RAW message or body]

On Wed, Mar 07, 2001 at 11:37:53AM +0000, David Faure wrote:
> On Wednesday 07 March 2001 07:31, Gordon Sadler wrote:
> > Let me apologize up front for the long-windedness, just thought I should
> > fully explain myself, as I'm purely an unknown around here.
> > 
> > Please find attached 2 patches, one each for kdelibs and kdebase.
> > 
> > Problem when documenting with kdoc, it appears to not parse namespace
> > declarations correctly.
> > 
> > If they are all on one line (ie namespace KIO{ jobs; } ) it fails to
> > parse the remainder of the file. Similarly if the namespace declaration
> > does not end with "};" , note the semicolon, it failes in the same
> > manner.
> 
> Which version of kdoc did you test ?
> I think this has been fixed in KDoc now. If you look at
> http://developer.kde.org/documentation/library/2.0-api/classref/kfile/KPropsDlgPlugin.html
> you'll see that this file has been parsed properly, even with the namespace KIO { class Job; }
> Same in 2.1-api.
> 
I am using kdoc from CVS HEAD, 2.0a52. The link you provide shows the
problem I found. From that link you can view kpropsdlg.h. From there you
can see one use of KIO { class Job; }, as you mention. Now from the
original page, click on Hierarchy, page down to KPropsDlgPlugin and
you'll notice all of the internal classes are being placed in KIO
namespace. From reading the code, that appears incorrect to me. My 'fix'
allowed kdoc to parse those children class correctly, not in namespace
KIO.

> I see in your patch that your version of kdoc didn't work with
> /** comment */
> but this has been fixed too.
> 
I did not specifically test this case, from reading the kdoc
documentation and the provided links to javadoc, it appeared The Right
Thing To Do. Sorry, if it's been fixed.

> > The patch also fixes one typo in arts/artsc/artsc.c.
> Applied :)
> 
> > Now you can produce a full set of documentation with kdoc, with one
> > MAJOR exception, kparts/dockmainwindow.h...
> > 
> > DockMainWindow inherits unknown class 'KDockMainWindow' which is caused
> > in kdeui/kdockwidget.h and a rather odd EXPORT_DOCKCLASS.
> > 
> > I tried using cvs log on kdockwidget.h to get some idea why NO_KDE2 and
> > EXPORT_DOCKCLASS are there. Looks like some compat code for kde1/kde2 ?
> 
> No, this is because those classes are apparently compileable on Windows too.
> 
> > Whatever the reason kdoc can't get passed kdockwidget.h:292
> > class EXPORT_DOCKCLASS KDockTabGroup : public KDockTabCtl
> > 
> > It just fails to read that, so on line 1024
> > class EXPORT_DOCKCLASS KDockMainWindow : public KMainWindow
> > 
> > it never gets the chance to realize that's a valid superclass for
> > DockMainWindow.
> 
> Yes, it seems this is still quite broken.
> I'll talk to Taj about this.
> 
> > You might wonder why I went to all this trouble rather than 'fixing'
> > kdoc? I'm not much for perl, I did read the source but... not sure I
> > understand it enough yet. The attached patches are purely aesthetic, but
> > they do 'fix' the problem for now -)
> 
> But they fix problems in the wrong place, and most of those are fixed
> in kdoc already.
> 
I agree it probably is the wrong place, I just wanted 'accurate' docs
without having to read the source all the time -). I still submit kdoc
has some problems with namespace KIO { class Job; } as noted above.

Just wish I understood perl a bit better to help with kdoc itself...

Thanks for your time.

Gordon Sadler
 
>> Visit http://master.kde.org/mailman/listinfo/kde-devel#unsub to unsubscribe <<

[prev in list] [next in list] [prev in thread] [next in thread]