Re: [Lift] Re: Documenting the source code / supplementing the API docs
Cool, great job - keep them coming :) On 26/02/2010, at 14.36, Stuart Roebuck wrote: > Okay - I've added a page to the wiki: > > http://wiki.github.com/dpp/liftweb/sitemap-basics > > > On Feb 26, 11:20 am, Stuart Roebuck wrote: >> Tim, >> >> Thanks - that sounds like a good idea. >> >> Stuart. >> >> On 26 Feb 2010, at 10:50, Timothy Perrett wrote: >> >> >> >>> Stuart, >> >>> You can still contribute to the wiki and of your findings or musings - >>> that is totally open. >> >>> Cheers, Tim > > -- > You received this message because you are subscribed to the Google Groups > "Lift" group. > To post to this group, send email to lift...@googlegroups.com. > To unsubscribe from this group, send email to > liftweb+unsubscr...@googlegroups.com. > 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 lift...@googlegroups.com. To unsubscribe from this group, send email to liftweb+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/liftweb?hl=en.
[Lift] Re: Documenting the source code / supplementing the API docs
Okay - I've added a page to the wiki: http://wiki.github.com/dpp/liftweb/sitemap-basics On Feb 26, 11:20 am, Stuart Roebuck wrote: > Tim, > > Thanks - that sounds like a good idea. > > Stuart. > > On 26 Feb 2010, at 10:50, Timothy Perrett wrote: > > > > > Stuart, > > > You can still contribute to the wiki and of your findings or musings - > > that is totally open. > > > Cheers, Tim -- You received this message because you are subscribed to the Google Groups "Lift" group. To post to this group, send email to lift...@googlegroups.com. To unsubscribe from this group, send email to liftweb+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/liftweb?hl=en.
Re: [Lift] Re: Documenting the source code / supplementing the API docs
Tim, Thanks - that sounds like a good idea. Stuart. On 26 Feb 2010, at 10:50, Timothy Perrett wrote: > Stuart, > > You can still contribute to the wiki and of your findings or musings - > that is totally open. > > Cheers, Tim -- You received this message because you are subscribed to the Google Groups "Lift" group. To post to this group, send email to lift...@googlegroups.com. To unsubscribe from this group, send email to liftweb+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/liftweb?hl=en.
[Lift] Re: Documenting the source code / supplementing the API docs
Stuart, You can still contribute to the wiki and of your findings or musings - that is totally open. Cheers, Tim On Feb 26, 9:59 am, Stuart Roebuck wrote: > I've spoken to David off- > list and unfortunately I am not comfortable signing the particular IP assignment > contract I was sent as it appears to me (but not to David) to be ambiguous in whether it covers what I commit or also any other code I am working on in connection with Lift > (e.g. the code of my business). > > I have offered to alter the wording but David has made it clear that > he will not move on the wording of this > and, as a lawyer, that it he knows what he is talking about better than I do. > > Having previously contributed to Apache Ant, Apache Cocoon and Apache James as well as making various minor contributions and bug fixes to other open source projects I have never had a problem in the past with the wording of such agreements with > open source projects > and would happily of signed the type of agreement currently used by Apache. (http://www.apache.org/licenses/icla.pdf) > > Unfortunately it looks like my attempt to contribute some > documentation is at a dead > end! Looking at the contract it is also clear that no other existing commiter may take my code or documentation and commit it, so thank you Ross for your offer, but it looks like that will not be possible. > > As I have said to David - > I really don't think that it should be so hard to accept contributions to this project. > > Stuart. > > As this contract is the one signed by all other commiters to the project, I am > > On Feb 23, 3:22 am, David Pollak > wrote: > > > > > The easiest thing is if Stuart signs an IP assignment, becomes a > > full-fledged committer and thus we keep the IP clean. > > > Stuart, if you're interested in learning more, please contact me off-list. > > > In terms of the documentation standards, I'm okay with anything that the > > rest of you-all want. I'm neither the best producer or consumer of docs, so > > my voice is a small one on this issue, other than to give hearty thanks to > > those who write documentation. > > > On Mon, Feb 22, 2010 at 1:05 PM, Stuart Roebuck > > wrote: > > > > 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 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
[Lift] Re: Documenting the source code / supplementing the API docs
I've spoken to David off- list and unfortunately I am not comfortable signing the particular IP assignment contract I was sent as it appears to me (but not to David) to be ambiguous in whether it covers what I commit or also any other code I am working on in connection with Lift (e.g. the code of my business). I have offered to alter the wording but David has made it clear that he will not move on the wording of this and, as a lawyer, that it he knows what he is talking about better than I do. Having previously contributed to Apache Ant, Apache Cocoon and Apache James as well as making various minor contributions and bug fixes to other open source projects I have never had a problem in the past with the wording of such agreements with open source projects and would happily of signed the type of agreement currently used by Apache. (http:// www.apache.org/licenses/icla.pdf) Unfortunately it looks like my attempt to contribute some documentation is at a dead end! Looking at the contract it is also clear that no other existing commiter may take my code or documentation and commit it, so thank you Ross for your offer, but it looks like that will not be possible. As I have said to David - I really don't think that it should be so hard to accept contributions to this project. Stuart. As this contract is the one signed by all other commiters to the project, I am On Feb 23, 3:22 am, David Pollak wrote: > The easiest thing is if Stuart signs an IP assignment, becomes a > full-fledged committer and thus we keep the IP clean. > > Stuart, if you're interested in learning more, please contact me off-list. > > In terms of the documentation standards, I'm okay with anything that the > rest of you-all want. I'm neither the best producer or consumer of docs, so > my voice is a small one on this issue, other than to give hearty thanks to > those who write documentation. > > On Mon, Feb 22, 2010 at 1:05 PM, Stuart Roebuck > wrote: > > > > > > > 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 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
Re: [Lift] Re: Documenting the source code / supplementing the API docs
The easiest thing is if Stuart signs an IP assignment, becomes a full-fledged committer and thus we keep the IP clean. Stuart, if you're interested in learning more, please contact me off-list. In terms of the documentation standards, I'm okay with anything that the rest of you-all want. I'm neither the best producer or consumer of docs, so my voice is a small one on this issue, other than to give hearty thanks to those who write documentation. On Mon, Feb 22, 2010 at 1:05 PM, Stuart Roebuck wrote: > 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 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 > >
Re: [Lift] Re: Documenting the source code / supplementing the API docs
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 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 lift...@googlegroups.com. >> To unsubscribe from this group, send email to >> liftweb+unsubscr...@googlegroups.com. >> For more options, visit this group >> athttp://groups.google.com/group/liftweb?hl=en. > -- > You received this message because you are subs
Re: [Lift] Re: Documenting the source code / supplementing the API docs
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 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 lift...@googlegroups.com. > To unsubscribe from this group, send email to > liftweb+unsubscr...@googlegroups.com. > 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 lift...@googlegroups.com. To unsubscribe from this group, send email to liftweb+unsubscr...@googlegroups.com. 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
Re: [Lift] Re: Documenting the source code / supplementing the API docs
Perhaps it's easier for me to do a fork on GitHub? Then any documentation submissions can be taken across at a time that suits whoever is doing it rather than synced with my submission timeline? On 22 Feb 2010, at 17:05, 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 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 lift...@googlegroups.com. > To unsubscribe from this group, send email to > liftweb+unsubscr...@googlegroups.com. > 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 lift...@googlegroups.com. To unsubscribe from this group, send email to liftweb+unsubscr...@googlegroups.com. For more options, visit this group athttp://groups.google.com/group/liftweb?hl=e
Re: [Lift] Re: Documenting the source code / supplementing the API docs
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 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 lift...@googlegroups.com. To unsubscribe from this group, send email to liftweb+unsubscr...@googlegroups.com. 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 lift...@googlegroups.com. >>> To unsubscribe from this group, send email to >>> liftweb+unsubscr...@googlegroups.com. >>> 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 lift...@googlegroups.com. > To unsubscribe from this group, send email to > liftweb+unsubscr...@googlegroups.com. > For more options, visit this group at > http://groups.google.com/group/liftweb?hl=en. > > -- You received this
[Lift] Re: Documenting the source code / supplementing the API docs
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 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 lift...@googlegroups.com. > >> To unsubscribe from this group, send email to > >> liftweb+unsubscr...@googlegroups.com. > >> 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 lift...@googlegroups.com. > > To unsubscribe from this group, send email to > > liftweb+unsubscr...@googlegroups.com. > > 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 lift...@googlegroups.com. To unsubscribe from this group, send email to liftweb+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/liftweb?hl=en.
