Great... okay, I’d better do some writing :-) In the absence of a decision I’ll try to minimise special coding in comments but use Scaladoc 2 standard if necessary rather than HTML as that makes it future proof but still readable for both.
Stuart On 22 Feb 2010, at 17:32, Ross Mellgren wrote: > I will do this, and give feed back if it ever becomes too much load. > > -Ross > > On Feb 22, 2010, at 12:05 PM, Timothy Perrett wrote: > >> We are interested in the contribution of course... I think the issue is >> mostly about how we take patches for this. Someone on the team would need to >> own this and merge your documentation changes into the master (provided DPP >> has no objections to this - seeing as its documentation I doubt he has) >> >> Any takers from the team? >> >> Cheers, Tim >> >> On 22 Feb 2010, at 16:14, Stuart Roebuck wrote: >> >>> Sorry for the slow response—was away for a family weekend! >>> >>> I have limited knowledge of Lift internals… >>> >>> However, my view is that it is often easier to document code when you >>> don't know it well than when you do, because you soon loose interest >>> in documenting things that are obvious to you. What I hope to do is >>> document the things that I need to know as I go along on the basis >>> that many of these things will also be important to others. It's an >>> agile rather than systematic approach if you see what I mean. >>> >>> I have no ego issues here. It's just a small way of giving to the >>> community in a win-win kind of way. If my contributions don't seem >>> helpful to anyone else then folk can say and I'm not going to >>> disappear in a torrent of abuse :-) >>> >>> Similarly, I'm not proposing some big project here. I'm talking about >>> a drip-drip of updates as I spot things that need documenting—I've got >>> plenty other stuff on my plate right now as I'm launching a company >>> based on a Lift based product in mid-year. >>> >>> Enough said… >>> >>> How do we resolve the documentation standard issue? (Scala 2.8 >>> Scaladoc2 or prior) David? >>> >>> Stuart. >>> >>> On Feb 19, 4:11 pm, Timothy Perrett <[email protected]> wrote: >>>> This could work - although, some parts of lift are very non-trivial and >>>> require good knowledge of lift internals. Do you have such knowledge or >>>> are you just hoping to contribute where you can with helpful information? >>>> Both are good, just trying to establish what you had in mind. >>>> >>>> Lift-util probably has the best docs at the moment, so if we could emulate >>>> that it would be good. >>>> >>>> Cheers, Tim >>>> >>>> On 19 Feb 2010, at 15:56, Ross Mellgren wrote: >>>> >>>> >>>> >>>>> If you can get an established standard on what the content and format >>>>> should be, I can work with you reviewing the patches and applying them. >>>> >>>>> But, need to get a concordance from the list on the content first. >>>> >>>>> -Ross >>>> >>>>> On Feb 19, 2010, at 10:53 AM, Stuart Roebuck wrote: >>>> >>>>>> I've had a bit of a break from Lift and coming back I find myself >>>>>> annoyed that I didn't write some notes last time and am having to go >>>>>> back to searching through the various bits of documentation to figure >>>>>> things out. >>>> >>>>>> Anyway, after much thought I decided that the best way to write my >>>>>> notes would be to supplement the API docs (ie. the Scaladoc >>>>>> documentation in the code base). so that I can view context sensitive >>>>>> help in my IDE of choice and others can benefit from my labours! >>>> >>>>>> So, question 1… >>>> >>>>>> The current API docs are very light on documentation and sometime ago >>>>>> I noticed some notice about removing documentation from the code >>>>>> base. Is there some policy about not having documentation in the >>>>>> code or any thought on whether it should adhere to the Scaladoc 2 >>>>>> syntax? >>>> >>>>>> Question 2… >>>> >>>>>> This is only really going to work if the process of submitting the >>>>>> documentation is reasonably straightforward so… What's the easiest >>>>>> possible way of submitting documentation changes to the code base? (if >>>>>> indeed this is something the core team would welcome). I was >>>>>> thinking of perhaps emailing git patch files to someone in the core >>>>>> team who can verify that the comments are right before checking them >>>>>> in. Any thoughts? >>>> >>>>>> If there is a reasonably explainable approach, it could be added as a >>>>>> Wiki page to encourage wider participation. >>>> >>>>>> Best, >>>> >>>>>> Stuart. >>>> >>>>>> -- >>>>>> You received this message because you are subscribed to the Google >>>>>> Groups "Lift" group. >>>>>> To post to this group, send email to [email protected]. >>>>>> To unsubscribe from this group, send email to >>>>>> [email protected]. >>>>>> For more options, visit this group >>>>>> athttp://groups.google.com/group/liftweb?hl=en. >>>> >>>>> -- >>>>> You received this message because you are subscribed to the Google Groups >>>>> "Lift" group. >>>>> To post to this group, send email to [email protected]. >>>>> To unsubscribe from this group, send email to >>>>> [email protected]. >>>>> For more options, visit this group >>>>> athttp://groups.google.com/group/liftweb?hl=en. >>> >>> -- >>> You received this message because you are subscribed to the Google Groups >>> "Lift" group. >>> To post to this group, send email to [email protected]. >>> To unsubscribe from this group, send email to >>> [email protected]. >>> For more options, visit this group at >>> http://groups.google.com/group/liftweb?hl=en. >>> >>> >> >> -- >> You received this message because you are subscribed to the Google Groups >> "Lift" group. >> To post to this group, send email to [email protected]. >> To unsubscribe from this group, send email to >> [email protected]. >> For more options, visit this group at >> http://groups.google.com/group/liftweb?hl=en. >> > > -- > You received this message because you are subscribed to the Google Groups > "Lift" group. > To post to this group, send email to [email protected]. > To unsubscribe from this group, send email to > [email protected]. > For more options, visit this group at > http://groups.google.com/group/liftweb?hl=en. > -- You received this message because you are subscribed to the Google Groups "Lift" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/liftweb?hl=en.
