gnustep-dev
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: autogsdoc change


From: Richard Frith-Macdonald
Subject: Re: autogsdoc change
Date: Tue, 6 Dec 2011 14:37:55 +0000

On 6 Dec 2011, at 12:52, Daniel Santos wrote:

> I would like to do some more. Since I am still getting to know the tool I 
> noticed that no cross references are generated among types (NSError refers 
> NSString but does not link to it.),

That's odd ... you should certainly be seeing cross references.  For instance 
if you look at the documentation of NSError at 
http://www.gnustep.org/resources/documentation/Developer/Base/Reference/index.html
 you will see cross references to NSString.  But that's a cross reference 
between classes ... I don't think there's any easy markup for referring to 
structures, bitfields, and  other plain C types.

> and no table of contents was generated. Is this always the case, or have I 
> missed any option ?

I guess you've missed an option ... there's markup to generate indexes (the 
'index' element) which you can put in a template document
(see 
http://www.gnustep.org/resources/documentation/Developer/Tools/Reference/gsdoc.html).
  There's also standardised stuff to put things in frames for easy navigation 
(with a table of contents).

> If I were to add these two features, can I just do it and then submit the 
> code to the list ?

Well, I think we already have those ... but maybe they don't work for you or 
are hard to figure out or find ... fixing/improving that might be good.  
Anything which makes it simpler/easier to do things is good.

> How do one suggest changes, and how do they get approved ?

The mailing list is a good place to find out if anyone objects to anything, and 
as I'm the maintainer for base, it's my job to make the decision ... but my 
basic principle is that if someone wants to work to improve something, I'm in 
favour of whatever makes them happy.

The project does have certain rules of course ... for anything other than very 
short fixes we need copyright assignment so that the code will be owned by the 
Free Software Foundation (they lease it back to you so you can do what you like 
with it, but they hold the copyright so they can legally chase anyone else who 
tries to incorporate it into proprietory software) ... so of course you must 
have written any contribution yourself.
Any code must conform to the coding standards and match the style of the 
existing code, and must of course work without breaking the existing code.

Beyond that, the aim is generally to improve the existing codebase ... make it 
simpler, more maintainable, easier to use, more clearly documented, better 
tested etc.  Adding new features is less obviously good ... if something new 
means the code is more complex, less maintainable, and harder to use then it 
had better be really useful (or necessary for OSX compatibility).
 
> If the development team doesn't think it has any value, one needs to know 
> before making the effort.

Well, if *you* think something is valuable, I would accept it even if I didn't 
... as long as it didn't look harmful (making things too complex or breaking 
existing code).  The more people who are interested in doing things, the better.
There certainly *are* things that need work in autogsdoc (a new version of the 
markup language to support the new objective-c 2.0 features, and corresponding 
support in the code for instance).

> PS : I would also try to modularize the code a bit more. (more methods, 
> shorter)

Yes (though not too short) ... I'm not proud of the autogsdoc code ... never 
had time to polish it ... I'm sure there's cleanup/consistency/restructuring 
that could be usefully done.




reply via email to

[Prev in Thread] Current Thread [Next in Thread]