You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@corinthia.apache.org by jan i <ja...@apache.org> on 2015/05/12 09:56:23 UTC
Code explanations in Wiki ?
Hi Peter.
Thanks for these super explanations, even though I work on the libraries at
the moment, they
were very interesting to read.
Should these mails (in a slightly modified form) go into our Wiki, maybe as
group "Thoughts
around the codebase" or something similar ?
Keep up the fun
rgds
jan I.
Re: Code explanations in Wiki ?
Posted by Gabriela Gibson <ga...@gmail.com>.
I Added a Doxygen page to the wiki, with a couple of links to Doxygen
and the salient page in the manual.
Added some space for Corinitha specific style rules and a todo list
for improving this page.
G
On 5/12/15, jan i <ja...@apache.org> wrote:
> Hi.
>
>
> Doxygen is a favorite of mine, it does what I like (most of the time).
>
> We do need some guidelines in the wiki, with examples, how/what to
> document, but apart from that, just go ahead.
>
> rgds
> jan I.
>
>
> On 12 May 2015 at 18:43, Gabriela Gibson <ga...@gmail.com> wrote:
>
>> Hi Peter,
>>
>> this is funny --- I DID confuse DocBook and Doxygen. I _meant_
>> Doxygen, I used it before, but for some reason I researched DocBook
>> instead and it stuck. So much for brand recognition.
>>
>> I nearly learned to set up the wrong thing there %-)
>>
>> G
>>
>> On 5/12/15, Peter Kelly <pm...@apache.org> wrote:
>> > I would suggest we stick with doxygen for in-code documentation, which
>> > is
>> > what is already used in the (few) parts of the codebase that do have
>> > API
>> > documentation.
>> >
>> > —
>> > Dr Peter M. Kelly
>> > pmkelly@apache.org
>> >
>> > PGP key: http://www.kellypmk.net/pgp-key <
>> http://www.kellypmk.net/pgp-key>
>> > (fingerprint 5435 6718 59F0 DD1F BFA0 5E46 2523 BAA1 44AE 2966)
>> >
>> >> On 12 May 2015, at 10:43 pm, jan i <ja...@apache.org> wrote:
>> >>
>> >> On 12 May 2015 at 17:39, Gabriela Gibson <ga...@gmail.com>
>> >> wrote:
>> >>
>> >>> Hi Jan,
>> >>>
>> >>> I've been writing a toy "queueAPI" that is built with cmake, and it
>> >>> just so happens that setting up and adding DocBook services is the
>> >>> next job on that project list.
>> >>>
>> >>> I think that should make a nice demo case.
>> >>>
>> >> +1 It does not need to be a perfect demo, just so that we can
>> >> understand
>> >> the flow, and where the information is kept.
>> >>
>> >> rgds
>> >> jan I.
>> >>
>> >>
>> >>>
>> >>> G
>> >>>
>> >>>
>> >>> On 5/12/15, jan i <ja...@apache.org> wrote:
>> >>>> On 12 May 2015 at 13:52, Gabriela Gibson <ga...@gmail.com>
>> >>> wrote:
>> >>>>
>> >>>>> Hi Peter,
>> >>>>>
>> >>>>> thanks for all the explanations :-)
>> >>>>>
>> >>>>> Further to Jan's suggestion, I think that the DF* library functions
>> >>>>> could benefit from DocBook comments, and be treated like an
>> >>>>> internal
>> >>>>> API.
>> >>>>>
>> >>>>> Whilst this is not for consumption for Corinthia users, it will be
>> >>>>> useful for devs in general and help to flatten the learning curve
>> >>>>> for
>> >>>>> newbies initially, and it's nice to just check on the generated
>> >>>>> HTML
>> >>>>> page to quickly find the correct tool or see easily if a better
>> method
>> >>>>> is available.
>> >>>>>
>> >>>>> I wouldn't mind writing the initial cut thereof and it would help
>> >>>>> me
>> >>>>> understand the DF library better too.
>> >>>>>
>> >>>> I am not against the idea, just have a few comments:
>> >>>> - If DocBook is maintained outside the source (header file) itself,
>> >>>> I
>> >>> would
>> >>>> never trust it. It is ok if it is extracted from the source file
>> >>>> - Dorte/I can make a subdir on our web for such documentation
>> >>>> (divide
>> >>>> in
>> >>>> internal/external/editor)
>> >>>>
>> >>>>
>> >>>> I never used DocBook, but different systems, could you please use a
>> few
>> >>>> words/examples of the workflow, and how we integrate it
>> >>>> in the build process.
>> >>>>
>> >>>> thanks
>> >>>> jan I.
>> >>>>
>> >>>>
>> >>>>> G
>> >>>>>
>> >>>>> On 5/12/15, jan i <ja...@apache.org> wrote:
>> >>>>>> Hi Peter.
>> >>>>>>
>> >>>>>> Thanks for these super explanations, even though I work on the
>> >>>>>> libraries
>> >>>>> at
>> >>>>>> the moment, they
>> >>>>>> were very interesting to read.
>> >>>>>>
>> >>>>>> Should these mails (in a slightly modified form) go into our Wiki,
>> >>>>>> maybe
>> >>>>> as
>> >>>>>> group "Thoughts
>> >>>>>> around the codebase" or something similar ?
>> >>>>>>
>> >>>>>> Keep up the fun
>> >>>>>> rgds
>> >>>>>> jan I.
>> >>>>>>
>> >>>>>
>> >>>>>
>> >>>>> --
>> >>>>> Visit my Coding Diary: http://gabriela-gibson.blogspot.com/
>> >>>>>
>> >>>>
>> >>>
>> >>>
>> >>> --
>> >>> Visit my Coding Diary: http://gabriela-gibson.blogspot.com/
>> >>>
>> >
>> >
>>
>>
>> --
>> Visit my Coding Diary: http://gabriela-gibson.blogspot.com/
>>
>
--
Visit my Coding Diary: http://gabriela-gibson.blogspot.com/
Re: Code explanations in Wiki ?
Posted by jan i <ja...@apache.org>.
Hi.
Doxygen is a favorite of mine, it does what I like (most of the time).
We do need some guidelines in the wiki, with examples, how/what to
document, but apart from that, just go ahead.
rgds
jan I.
On 12 May 2015 at 18:43, Gabriela Gibson <ga...@gmail.com> wrote:
> Hi Peter,
>
> this is funny --- I DID confuse DocBook and Doxygen. I _meant_
> Doxygen, I used it before, but for some reason I researched DocBook
> instead and it stuck. So much for brand recognition.
>
> I nearly learned to set up the wrong thing there %-)
>
> G
>
> On 5/12/15, Peter Kelly <pm...@apache.org> wrote:
> > I would suggest we stick with doxygen for in-code documentation, which is
> > what is already used in the (few) parts of the codebase that do have API
> > documentation.
> >
> > —
> > Dr Peter M. Kelly
> > pmkelly@apache.org
> >
> > PGP key: http://www.kellypmk.net/pgp-key <
> http://www.kellypmk.net/pgp-key>
> > (fingerprint 5435 6718 59F0 DD1F BFA0 5E46 2523 BAA1 44AE 2966)
> >
> >> On 12 May 2015, at 10:43 pm, jan i <ja...@apache.org> wrote:
> >>
> >> On 12 May 2015 at 17:39, Gabriela Gibson <ga...@gmail.com>
> >> wrote:
> >>
> >>> Hi Jan,
> >>>
> >>> I've been writing a toy "queueAPI" that is built with cmake, and it
> >>> just so happens that setting up and adding DocBook services is the
> >>> next job on that project list.
> >>>
> >>> I think that should make a nice demo case.
> >>>
> >> +1 It does not need to be a perfect demo, just so that we can understand
> >> the flow, and where the information is kept.
> >>
> >> rgds
> >> jan I.
> >>
> >>
> >>>
> >>> G
> >>>
> >>>
> >>> On 5/12/15, jan i <ja...@apache.org> wrote:
> >>>> On 12 May 2015 at 13:52, Gabriela Gibson <ga...@gmail.com>
> >>> wrote:
> >>>>
> >>>>> Hi Peter,
> >>>>>
> >>>>> thanks for all the explanations :-)
> >>>>>
> >>>>> Further to Jan's suggestion, I think that the DF* library functions
> >>>>> could benefit from DocBook comments, and be treated like an internal
> >>>>> API.
> >>>>>
> >>>>> Whilst this is not for consumption for Corinthia users, it will be
> >>>>> useful for devs in general and help to flatten the learning curve for
> >>>>> newbies initially, and it's nice to just check on the generated HTML
> >>>>> page to quickly find the correct tool or see easily if a better
> method
> >>>>> is available.
> >>>>>
> >>>>> I wouldn't mind writing the initial cut thereof and it would help me
> >>>>> understand the DF library better too.
> >>>>>
> >>>> I am not against the idea, just have a few comments:
> >>>> - If DocBook is maintained outside the source (header file) itself, I
> >>> would
> >>>> never trust it. It is ok if it is extracted from the source file
> >>>> - Dorte/I can make a subdir on our web for such documentation (divide
> >>>> in
> >>>> internal/external/editor)
> >>>>
> >>>>
> >>>> I never used DocBook, but different systems, could you please use a
> few
> >>>> words/examples of the workflow, and how we integrate it
> >>>> in the build process.
> >>>>
> >>>> thanks
> >>>> jan I.
> >>>>
> >>>>
> >>>>> G
> >>>>>
> >>>>> On 5/12/15, jan i <ja...@apache.org> wrote:
> >>>>>> Hi Peter.
> >>>>>>
> >>>>>> Thanks for these super explanations, even though I work on the
> >>>>>> libraries
> >>>>> at
> >>>>>> the moment, they
> >>>>>> were very interesting to read.
> >>>>>>
> >>>>>> Should these mails (in a slightly modified form) go into our Wiki,
> >>>>>> maybe
> >>>>> as
> >>>>>> group "Thoughts
> >>>>>> around the codebase" or something similar ?
> >>>>>>
> >>>>>> Keep up the fun
> >>>>>> rgds
> >>>>>> jan I.
> >>>>>>
> >>>>>
> >>>>>
> >>>>> --
> >>>>> Visit my Coding Diary: http://gabriela-gibson.blogspot.com/
> >>>>>
> >>>>
> >>>
> >>>
> >>> --
> >>> Visit my Coding Diary: http://gabriela-gibson.blogspot.com/
> >>>
> >
> >
>
>
> --
> Visit my Coding Diary: http://gabriela-gibson.blogspot.com/
>
Re: Code explanations in Wiki ?
Posted by Gabriela Gibson <ga...@gmail.com>.
Hi Peter,
this is funny --- I DID confuse DocBook and Doxygen. I _meant_
Doxygen, I used it before, but for some reason I researched DocBook
instead and it stuck. So much for brand recognition.
I nearly learned to set up the wrong thing there %-)
G
On 5/12/15, Peter Kelly <pm...@apache.org> wrote:
> I would suggest we stick with doxygen for in-code documentation, which is
> what is already used in the (few) parts of the codebase that do have API
> documentation.
>
> —
> Dr Peter M. Kelly
> pmkelly@apache.org
>
> PGP key: http://www.kellypmk.net/pgp-key <http://www.kellypmk.net/pgp-key>
> (fingerprint 5435 6718 59F0 DD1F BFA0 5E46 2523 BAA1 44AE 2966)
>
>> On 12 May 2015, at 10:43 pm, jan i <ja...@apache.org> wrote:
>>
>> On 12 May 2015 at 17:39, Gabriela Gibson <ga...@gmail.com>
>> wrote:
>>
>>> Hi Jan,
>>>
>>> I've been writing a toy "queueAPI" that is built with cmake, and it
>>> just so happens that setting up and adding DocBook services is the
>>> next job on that project list.
>>>
>>> I think that should make a nice demo case.
>>>
>> +1 It does not need to be a perfect demo, just so that we can understand
>> the flow, and where the information is kept.
>>
>> rgds
>> jan I.
>>
>>
>>>
>>> G
>>>
>>>
>>> On 5/12/15, jan i <ja...@apache.org> wrote:
>>>> On 12 May 2015 at 13:52, Gabriela Gibson <ga...@gmail.com>
>>> wrote:
>>>>
>>>>> Hi Peter,
>>>>>
>>>>> thanks for all the explanations :-)
>>>>>
>>>>> Further to Jan's suggestion, I think that the DF* library functions
>>>>> could benefit from DocBook comments, and be treated like an internal
>>>>> API.
>>>>>
>>>>> Whilst this is not for consumption for Corinthia users, it will be
>>>>> useful for devs in general and help to flatten the learning curve for
>>>>> newbies initially, and it's nice to just check on the generated HTML
>>>>> page to quickly find the correct tool or see easily if a better method
>>>>> is available.
>>>>>
>>>>> I wouldn't mind writing the initial cut thereof and it would help me
>>>>> understand the DF library better too.
>>>>>
>>>> I am not against the idea, just have a few comments:
>>>> - If DocBook is maintained outside the source (header file) itself, I
>>> would
>>>> never trust it. It is ok if it is extracted from the source file
>>>> - Dorte/I can make a subdir on our web for such documentation (divide
>>>> in
>>>> internal/external/editor)
>>>>
>>>>
>>>> I never used DocBook, but different systems, could you please use a few
>>>> words/examples of the workflow, and how we integrate it
>>>> in the build process.
>>>>
>>>> thanks
>>>> jan I.
>>>>
>>>>
>>>>> G
>>>>>
>>>>> On 5/12/15, jan i <ja...@apache.org> wrote:
>>>>>> Hi Peter.
>>>>>>
>>>>>> Thanks for these super explanations, even though I work on the
>>>>>> libraries
>>>>> at
>>>>>> the moment, they
>>>>>> were very interesting to read.
>>>>>>
>>>>>> Should these mails (in a slightly modified form) go into our Wiki,
>>>>>> maybe
>>>>> as
>>>>>> group "Thoughts
>>>>>> around the codebase" or something similar ?
>>>>>>
>>>>>> Keep up the fun
>>>>>> rgds
>>>>>> jan I.
>>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> Visit my Coding Diary: http://gabriela-gibson.blogspot.com/
>>>>>
>>>>
>>>
>>>
>>> --
>>> Visit my Coding Diary: http://gabriela-gibson.blogspot.com/
>>>
>
>
--
Visit my Coding Diary: http://gabriela-gibson.blogspot.com/
Re: Code explanations in Wiki ?
Posted by Peter Kelly <pm...@apache.org>.
I would suggest we stick with doxygen for in-code documentation, which is what is already used in the (few) parts of the codebase that do have API documentation.
—
Dr Peter M. Kelly
pmkelly@apache.org
PGP key: http://www.kellypmk.net/pgp-key <http://www.kellypmk.net/pgp-key>
(fingerprint 5435 6718 59F0 DD1F BFA0 5E46 2523 BAA1 44AE 2966)
> On 12 May 2015, at 10:43 pm, jan i <ja...@apache.org> wrote:
>
> On 12 May 2015 at 17:39, Gabriela Gibson <ga...@gmail.com> wrote:
>
>> Hi Jan,
>>
>> I've been writing a toy "queueAPI" that is built with cmake, and it
>> just so happens that setting up and adding DocBook services is the
>> next job on that project list.
>>
>> I think that should make a nice demo case.
>>
> +1 It does not need to be a perfect demo, just so that we can understand
> the flow, and where the information is kept.
>
> rgds
> jan I.
>
>
>>
>> G
>>
>>
>> On 5/12/15, jan i <ja...@apache.org> wrote:
>>> On 12 May 2015 at 13:52, Gabriela Gibson <ga...@gmail.com>
>> wrote:
>>>
>>>> Hi Peter,
>>>>
>>>> thanks for all the explanations :-)
>>>>
>>>> Further to Jan's suggestion, I think that the DF* library functions
>>>> could benefit from DocBook comments, and be treated like an internal
>>>> API.
>>>>
>>>> Whilst this is not for consumption for Corinthia users, it will be
>>>> useful for devs in general and help to flatten the learning curve for
>>>> newbies initially, and it's nice to just check on the generated HTML
>>>> page to quickly find the correct tool or see easily if a better method
>>>> is available.
>>>>
>>>> I wouldn't mind writing the initial cut thereof and it would help me
>>>> understand the DF library better too.
>>>>
>>> I am not against the idea, just have a few comments:
>>> - If DocBook is maintained outside the source (header file) itself, I
>> would
>>> never trust it. It is ok if it is extracted from the source file
>>> - Dorte/I can make a subdir on our web for such documentation (divide in
>>> internal/external/editor)
>>>
>>>
>>> I never used DocBook, but different systems, could you please use a few
>>> words/examples of the workflow, and how we integrate it
>>> in the build process.
>>>
>>> thanks
>>> jan I.
>>>
>>>
>>>> G
>>>>
>>>> On 5/12/15, jan i <ja...@apache.org> wrote:
>>>>> Hi Peter.
>>>>>
>>>>> Thanks for these super explanations, even though I work on the
>>>>> libraries
>>>> at
>>>>> the moment, they
>>>>> were very interesting to read.
>>>>>
>>>>> Should these mails (in a slightly modified form) go into our Wiki,
>>>>> maybe
>>>> as
>>>>> group "Thoughts
>>>>> around the codebase" or something similar ?
>>>>>
>>>>> Keep up the fun
>>>>> rgds
>>>>> jan I.
>>>>>
>>>>
>>>>
>>>> --
>>>> Visit my Coding Diary: http://gabriela-gibson.blogspot.com/
>>>>
>>>
>>
>>
>> --
>> Visit my Coding Diary: http://gabriela-gibson.blogspot.com/
>>
Re: Code explanations in Wiki ?
Posted by jan i <ja...@apache.org>.
On 12 May 2015 at 17:39, Gabriela Gibson <ga...@gmail.com> wrote:
> Hi Jan,
>
> I've been writing a toy "queueAPI" that is built with cmake, and it
> just so happens that setting up and adding DocBook services is the
> next job on that project list.
>
> I think that should make a nice demo case.
>
+1 It does not need to be a perfect demo, just so that we can understand
the flow, and where the information is kept.
rgds
jan I.
>
> G
>
>
> On 5/12/15, jan i <ja...@apache.org> wrote:
> > On 12 May 2015 at 13:52, Gabriela Gibson <ga...@gmail.com>
> wrote:
> >
> >> Hi Peter,
> >>
> >> thanks for all the explanations :-)
> >>
> >> Further to Jan's suggestion, I think that the DF* library functions
> >> could benefit from DocBook comments, and be treated like an internal
> >> API.
> >>
> >> Whilst this is not for consumption for Corinthia users, it will be
> >> useful for devs in general and help to flatten the learning curve for
> >> newbies initially, and it's nice to just check on the generated HTML
> >> page to quickly find the correct tool or see easily if a better method
> >> is available.
> >>
> >> I wouldn't mind writing the initial cut thereof and it would help me
> >> understand the DF library better too.
> >>
> > I am not against the idea, just have a few comments:
> > - If DocBook is maintained outside the source (header file) itself, I
> would
> > never trust it. It is ok if it is extracted from the source file
> > - Dorte/I can make a subdir on our web for such documentation (divide in
> > internal/external/editor)
> >
> >
> > I never used DocBook, but different systems, could you please use a few
> > words/examples of the workflow, and how we integrate it
> > in the build process.
> >
> > thanks
> > jan I.
> >
> >
> >> G
> >>
> >> On 5/12/15, jan i <ja...@apache.org> wrote:
> >> > Hi Peter.
> >> >
> >> > Thanks for these super explanations, even though I work on the
> >> > libraries
> >> at
> >> > the moment, they
> >> > were very interesting to read.
> >> >
> >> > Should these mails (in a slightly modified form) go into our Wiki,
> >> > maybe
> >> as
> >> > group "Thoughts
> >> > around the codebase" or something similar ?
> >> >
> >> > Keep up the fun
> >> > rgds
> >> > jan I.
> >> >
> >>
> >>
> >> --
> >> Visit my Coding Diary: http://gabriela-gibson.blogspot.com/
> >>
> >
>
>
> --
> Visit my Coding Diary: http://gabriela-gibson.blogspot.com/
>
Re: Code explanations in Wiki ?
Posted by Gabriela Gibson <ga...@gmail.com>.
Hi Jan,
I've been writing a toy "queueAPI" that is built with cmake, and it
just so happens that setting up and adding DocBook services is the
next job on that project list.
I think that should make a nice demo case.
G
On 5/12/15, jan i <ja...@apache.org> wrote:
> On 12 May 2015 at 13:52, Gabriela Gibson <ga...@gmail.com> wrote:
>
>> Hi Peter,
>>
>> thanks for all the explanations :-)
>>
>> Further to Jan's suggestion, I think that the DF* library functions
>> could benefit from DocBook comments, and be treated like an internal
>> API.
>>
>> Whilst this is not for consumption for Corinthia users, it will be
>> useful for devs in general and help to flatten the learning curve for
>> newbies initially, and it's nice to just check on the generated HTML
>> page to quickly find the correct tool or see easily if a better method
>> is available.
>>
>> I wouldn't mind writing the initial cut thereof and it would help me
>> understand the DF library better too.
>>
> I am not against the idea, just have a few comments:
> - If DocBook is maintained outside the source (header file) itself, I would
> never trust it. It is ok if it is extracted from the source file
> - Dorte/I can make a subdir on our web for such documentation (divide in
> internal/external/editor)
>
>
> I never used DocBook, but different systems, could you please use a few
> words/examples of the workflow, and how we integrate it
> in the build process.
>
> thanks
> jan I.
>
>
>> G
>>
>> On 5/12/15, jan i <ja...@apache.org> wrote:
>> > Hi Peter.
>> >
>> > Thanks for these super explanations, even though I work on the
>> > libraries
>> at
>> > the moment, they
>> > were very interesting to read.
>> >
>> > Should these mails (in a slightly modified form) go into our Wiki,
>> > maybe
>> as
>> > group "Thoughts
>> > around the codebase" or something similar ?
>> >
>> > Keep up the fun
>> > rgds
>> > jan I.
>> >
>>
>>
>> --
>> Visit my Coding Diary: http://gabriela-gibson.blogspot.com/
>>
>
--
Visit my Coding Diary: http://gabriela-gibson.blogspot.com/
Re: Code explanations in Wiki ?
Posted by jan i <ja...@apache.org>.
On 12 May 2015 at 13:52, Gabriela Gibson <ga...@gmail.com> wrote:
> Hi Peter,
>
> thanks for all the explanations :-)
>
> Further to Jan's suggestion, I think that the DF* library functions
> could benefit from DocBook comments, and be treated like an internal
> API.
>
> Whilst this is not for consumption for Corinthia users, it will be
> useful for devs in general and help to flatten the learning curve for
> newbies initially, and it's nice to just check on the generated HTML
> page to quickly find the correct tool or see easily if a better method
> is available.
>
> I wouldn't mind writing the initial cut thereof and it would help me
> understand the DF library better too.
>
I am not against the idea, just have a few comments:
- If DocBook is maintained outside the source (header file) itself, I would
never trust it. It is ok if it is extracted from the source file
- Dorte/I can make a subdir on our web for such documentation (divide in
internal/external/editor)
I never used DocBook, but different systems, could you please use a few
words/examples of the workflow, and how we integrate it
in the build process.
thanks
jan I.
> G
>
> On 5/12/15, jan i <ja...@apache.org> wrote:
> > Hi Peter.
> >
> > Thanks for these super explanations, even though I work on the libraries
> at
> > the moment, they
> > were very interesting to read.
> >
> > Should these mails (in a slightly modified form) go into our Wiki, maybe
> as
> > group "Thoughts
> > around the codebase" or something similar ?
> >
> > Keep up the fun
> > rgds
> > jan I.
> >
>
>
> --
> Visit my Coding Diary: http://gabriela-gibson.blogspot.com/
>
Re: Code explanations in Wiki ?
Posted by Gabriela Gibson <ga...@gmail.com>.
Hi Peter,
thanks for all the explanations :-)
Further to Jan's suggestion, I think that the DF* library functions
could benefit from DocBook comments, and be treated like an internal
API.
Whilst this is not for consumption for Corinthia users, it will be
useful for devs in general and help to flatten the learning curve for
newbies initially, and it's nice to just check on the generated HTML
page to quickly find the correct tool or see easily if a better method
is available.
I wouldn't mind writing the initial cut thereof and it would help me
understand the DF library better too.
G
On 5/12/15, jan i <ja...@apache.org> wrote:
> Hi Peter.
>
> Thanks for these super explanations, even though I work on the libraries at
> the moment, they
> were very interesting to read.
>
> Should these mails (in a slightly modified form) go into our Wiki, maybe as
> group "Thoughts
> around the codebase" or something similar ?
>
> Keep up the fun
> rgds
> jan I.
>
--
Visit my Coding Diary: http://gabriela-gibson.blogspot.com/