beside iohannes's howto? this list ...
tim, who thinks the api documented should be improved ...
But I think looking to the code of an object which has a similar behaviour is maybe faster than reading a big api ...
LG Georg
It's nice to have both. If you have a well documented API it's much easier to decipher the source, since you can clearly see a description of a function, its arguments, its return value, and what file it resides in.
If folks could provide me with information, I could spend some time gluing it together into something nice looking.
-ian
Georg Holzmann wrote:
beside iohannes's howto? this list ...
tim, who thinks the api documented should be improved ...
But I think looking to the code of an object which has a similar behaviour is maybe faster than reading a big api ...
LG Georg
It's nice to have both. If you have a well documented API it's much easier to decipher the source, since you can clearly see a description of a function, its arguments, its return value, and what file it resides in.
If folks could provide me with information, I could spend some time gluing it together into something nice looking.
i think the basic problem with api documentation is maintening it, not generating it. and i'm sure if you maintain the old external how-to a bit no one will bother you. it you start an api documentation then you should find a form that allows others to maintain it with you (wiki?) or you'll have to stick with it for years. api changes are rare but they happen (e.g. naming of externals in libs (keyword: nameclash) + help patches has changed or maybe will change. i know this is not directly a part of the api - it's part of the documentation though).
i'ld be glad if there would be a better starting point then the how-to.
and: nice working is better than nice looking :)
lg martin
On Jan 6, 2005, at 4:50 AM, martin pichlmair wrote:
It's nice to have both. If you have a well documented API it's much easier to decipher the source, since you can clearly see a description of a function, its arguments, its return value, and what file it resides in.
If folks could provide me with information, I could spend some time gluing it together into something nice looking.
i think the basic problem with api documentation is maintening it, not generating it. and i'm sure if you maintain the old external how-to a bit no one will bother you. it you start an api documentation then you should find a form that allows others to maintain it with you (wiki?) or you'll have to stick with it for years. api changes are rare but they happen (e.g. naming of externals in libs (keyword: nameclash) + help patches has changed or maybe will change. i know this is not directly a part of the api - it's part of the documentation though).
i'ld be glad if there would be a better starting point then the how-to.
and: nice working is better than nice looking :)
How about something like HeaderDoc? Its an open standard, reasonably common, and easy to implement. Plus the source for the API docs would be in the headers themselves, and therefore more likely to be maintained by those making changes to the API.
.hc
________________________________________________________________________ ____
Man has survived hitherto because he was too ignorant to know how to realize his wishes. Now that he can realize them, he must either change them, or perish. -William Carlos Williams
and: nice working is better than nice looking :)
Of course. But nice looking never hurt no one ;) or did it?:
"America is like the pretty girl in High School who said 'everyone hates me because I'm pretty.' No, everyone hates you, because you're a jerk." -Laurie Anderson from "The End of the Moon"
Sorry for the tangent.
How about something like HeaderDoc? Its an open standard, reasonably common, and easy to implement. Plus the source for the API docs would be in the headers themselves, and therefore more likely to be maintained by those making changes to the API.
I'm not familiar with HeaderDoc per se, but I was thinking of something that would have a good degree of automation. The Java documentation system is nice in its ability to automatically generate standardized API docs. Automatic links to functions and syntax hilighting would be good for web viewing. Also if we use something like HeaderDoc there would at least be a stub document for each source file, which could be added to as time allows.
I'll start looking at solutions, starting with HeaderDoc and hope to have a skeleton up within the next week. Adding to it and making it more specific will need to be up to those who know more about it, since the whole reason I'm doing this is because I need to use it ;)
-Ian
.hc
Man has survived hitherto because he was too ignorant to know how to realize his wishes. Now that he can realize them, he must either change them, or perish. -William Carlos Williams
PD-dev mailing list PD-dev@iem.at http://iem.at/cgi-bin/mailman/listinfo/pd-dev
sorry for getting slightly off topic.
and: nice working is better than nice looking :)
Of course. But nice looking never hurt no one ;) or did it?:
of course it did. aesthetics sometimes has the tendency to shadow functionality. think of the well known and beautiful philipe starck lemon squeezer: it is a pain (or at least "messy") to use. that is not what i call good design. a big deal of beauty lies in functionality, too.
and concerning pd: all attempts of beautifying it did not contribute so much to the pleasure of working with it as the interactive way of working itself - thus functionality again - did.
"America is like the pretty girl in High School who said 'everyone hates me because I'm pretty.' No, everyone hates you, because you're a jerk." -Laurie Anderson from "The End of the Moon"
Sorry for the tangent.
hehe
martin
On Sun, Jan 09, 2005 at 05:13:01PM +0100, martin pichlmair wrote:
and: nice working is better than nice looking :)
Of course. But nice looking never hurt no one ;) or did it?:
of course it did. aesthetics sometimes has the tendency to shadow functionality. think of the well known and beautiful philipe starck lemon squeezer: it is a pain (or at least "messy") to use. that is not what i call good design. a big deal of beauty lies in functionality, too.
http://www.metropolismag.com/cda/story.php?artid=95
(Ignore the very first paragraph - there is something wrong with their CMS causing it to take an irrelevant first paragraph from a different article)
Best,
Chris. ------------------- chris@mccormick.cx http://mccormick.cx
On Sat, 8 Jan 2005, Ian Smith-Heisters wrote:
and: nice working is better than nice looking :)
Of course. But nice looking never hurt no one ;) or did it?: "America is like the pretty girl in High School who said 'everyone hates me because I'm pretty.' No, everyone hates you, because you're a jerk." -Laurie Anderson from "The End of the Moon" Sorry for the tangent.
But not much later in high school, one learns that not all ugly people make nice friends, or interesting ones.
_____________________________________________________________________ Mathieu Bouchard -=- Montréal QC Canada -=- http://artengine.ca/matju
-
Chris McCormick -
Georg Holzmann -
Hans-Christoph Steiner -
Ian Smith-Heisters -
martin pichlmair -
Mathieu Bouchard