corinthia-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jan i <j...@apache.org>
Subject Re: Code explanations in Wiki ?
Date Tue, 12 May 2015 16:46:30 GMT
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 <gabriela.gibson@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 <pmkelly@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 <jani@apache.org> wrote:
> >>
> >> On 12 May 2015 at 17:39, Gabriela Gibson <gabriela.gibson@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 <jani@apache.org> wrote:
> >>>> On 12 May 2015 at 13:52, Gabriela Gibson <gabriela.gibson@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 <jani@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/
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message