yes this was my gut feeling too. What I like with method annotation is that we can get people writing executable examples. Once I discussed with lukas about tests and to me there is a difference between writing tests for coverage and for public consumption. For public consumption you write meaningful api sequence, mini scenario.
Stef On Apr 8, 2010, at 11:49 PM, Michael Roberts wrote: > Torsten, i appreciate the thought you are putting in. I just wonder if > the definition of the help (the raw content) should also be bound up > with the definition of the overall structure? I also wonder if I want > to bend the help system in a way that it is not intended. > > For me i want something that is like python doc strings, and the great > python package documentation available, ... but in a more smalltalk > in-image manner. So that's why i think of it in terms of annotations. > Having the help be in its own help class, on the class side, without > any real behavior is a design smell to me. I don't really like heavy > class-side programming; the class doesn't really offer any behaviour > or scale across the image. I guess i want to see docs spread across > the system. you want them central? to me the classes are really just > annotations, apart from as you say needing to provide the role of > structure for the nested content. > > my use case is that the documentation must be next to the code it is > documenting. the network package is a good example. Since the API is > in a state of flux, and no one knew how the 'new' api was supposed to > work, it could really benefit detailed documentation for each version > of pharo. it will change likely for each major version. the docs need > to be in the package. fine, we can have the requisite 2 classes > already in the image. that is ok. but it would be better to have the > doc content on the actual system classes themselves. Like > NetNameResolver. and Socket, etc. so i either have to have my custom > class reference them, in some imperative manner, or i need to build a > builder.. or something. I had imagined it would be possible to have > standard places/hooks for packages and classes, where annotations > would go. for example like stef says we could pull out the class > comment. > > also, i imagine if documenting the system, in a system wide manner, > was successful we would have lots of doit expressions. some mashup > between workspaces, profstef, and hypertext. in that case it would be > nice to somehow link doc expressions that are really little test > assertions together, so we can actually test the docs to make sure > that they validate against the system code. I think the SBE/PBE latex > sources had this idea in them. And Adrian K has posted examples of > these nice extensions to sunit that read very well. I would like that > feeling somehow integrated, otherwise we won't be able to maintain the > sanity of our docs either. so i guess i'm kinda with stef's comments > later in this thread. > > but anyway, we start with zero in-image documentation. for me we must > just have a doc system that scales. i really want to see the docs in > the packages, not in a single central package. we'll just have to see > how it plays out. i don't want to take away from building a 'help > system' that would let you provide F1 style help for an actual > application - we just desperately need system level documentation to > take Pharo to the next level. I guess I see no need for defining > inter-help structure because I think for system level docs it can be > entirely derived. each package, class, method can all be annotated in > a consistent manner. programming examples could be attached to > classes in a standard manner. you could then provide a browser giving > A-Z, hierarchy, package, classes, search, index, etc views on these > annotations. This is not what you are trying to do with your help > system, but i see this as a subset of the intent and a lot of the > logic already there. i'm not sure if i'm making any sense... > > cheers, > Mike > > _______________________________________________ > Pharo-project mailing list > [email protected] > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project _______________________________________________ Pharo-project mailing list [email protected] http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
