bugGNUstep - Bugs: bug #33056, Incorrect GSDoc output if #import...

Group
 
 

bug #33056: Incorrect GSDoc output if #import is omitted in a header

Submitter:  Quentin Mathé <qmathe>
Submitted:  Tue 12 Apr 2011 03:09:43 PM UTC
   
 
Category:  Base/Foundation Severity:  2 - Minor
Item Group:  Bug Status:  Wont Fix
Privacy:  Public Assigned to:  None
Open/Closed:  Analyzed
* Mandatory Fields

Add a New Comment Rich Markup
   

Tue 12 Apr 2011 05:48:59 PM UTC, comment #2: 

The mail address '<qmathe@club-internet.fr>' belongs to 'Author:' in ETFragment.h, so this should be ok. Autosgdoc documentation states:

"Any line of the form ' Author : name <email-address>', or ' By : name <email-address>', or ' Author : name' or ' By : name' will be recognised and converted to an author element, possibly containing an email element."

This is from the Extra markup section of http://www.gnustep.org/resources/documentation/Developer/Tools/Reference/index.html

You can take look at ETFragment.h, it's a reduced test case.

The issue could be that AGSParser gets into an invalid state when no #import/include is parsed. Given that all ObjC files include an #import/include usually, the problem almost never arises.

It looks like AGSParser parses the top comment twice, as the ETFragment protocol comment and as the main header comment. That's could be due to the fact, it relies on parsing #import or some preprocessor directive to reset the ivar 'comment' that acts a documentation accumulator.

Quentin Mathé <qmathe>
Group Member
Tue 12 Apr 2011 04:51:43 PM UTC, comment #1: 

I think this is due to an error in ETFragment.h rather than an autogsdoc bug.

Autogsdoc comments contain xml markup ... so if you want to use a literal '<' you must write it as '&lt;' ... but the header contains '<qmathe@club-internet.fr>' ... bad xml.

However, it might be worth implementing some special-case handling to recognize email addresses in comments (after all, we already support a degree of special handling for lines containing 'Author:') and quote the '<' and '>' characters.

Richard Frith-Macdonald <CaS>
Group Member
Tue 12 Apr 2011 03:09:43 PM UTC, original submission:  

Hi,

When I give the attached ETFragment.h header to autogsdoc, the parsing fails as follows:

autogsdoc -Project TestUI -MakeFrames YES ~/reps/trunkEtoile/Frameworks/EtoileUI/Headers/ETFragment.h
at line: 33 column: 18 ... error parsing attribute name
at line: 33 column: 18 ... attributes construct error
at line: 33 column: 18 ... Couldn't find end of Start Tag qmathe
2011-04-12 16:56:09.784 autogsdoc[23131] WARNING ETFragment.gsdoc is not a valid document
2011-04-12 16:56:09.792 autogsdoc[23131]

NOTE: Generating a simple introductory page for your project.
To replace this with a custom version, edit the gsdoc file
named TestUI.gsdoc in the documentation output directory.
Then include this file in the arguments to autogsdoc.

at line: 33 column: 18 ... error parsing attribute name
at line: 33 column: 18 ... attributes construct error
at line: 33 column: 18 ... Couldn't find end of Start Tag qmathe
2011-04-12 16:56:09.795 autogsdoc[23131] WARNING ETFragment.gsdoc is not a valid document
2011-04-12 16:56:09.796 autogsdoc[23131] Non-block element 'abstract' in block ...
2011-04-12 16:56:09.796 autogsdoc[23131] <abstract>
            Protocol to represent all visual fragments whether
            or not they are explictly represented in the layout item
            tree.
          </abstract>

If I uncomment the #import line, everything just works fine.

I added ETFragment.gsdoc in attachment too.

Quentin.

Quentin Mathé <qmathe>
Group Member

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #23226:  ETFragment.h added by qmathe (356B - text/x-chdr)
file #23227:  ETFragment.gsdoc added by qmathe (1KiB - application/octet-stream)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by CaS (Posted a comment)
  • -email is unavailable- added by qmathe (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 4 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2011-04-12 CaS StatusNone Wont Fix
        Open/ClosedOpen Analyzed
    2011-04-12 qmathe Attached File- Added ETFragment.h, #23226
        Attached File- Added ETFragment.gsdoc, #23227

    Back to the top

    Powered by Savane 3.13-02a9.
    Corresponding source code