corinthia-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gabriela Gibson <gabriela.gib...@gmail.com>
Subject Re: Code explanations in Wiki ?
Date Tue, 12 May 2015 16:43:46 GMT
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
View raw message