[Gluster-devel] Better organization for code documentation [Was: Developer Documentation for datastructures in gluster]

[Anand Avati]

On Tue, Jul 22, 2014 at 7:35 AM, Kaushal M <kshlmster at gmail.com> wrote:

> Hey everyone,
>
> While I was writing the documentation for the options framework, I
> thought up of a way to better organize the code documentation we are
> creating now. I've posted a patch for review that implements this
> organization. [1]
>
> Copying the description from the patch I've posted for review,
> ```
> A new directory hierarchy has been created in doc/code for the code
> documentation, which follows the general GlusterFS source hierarchy.
> Each GlusterFS module has an entry in this tree. The source directory of
> every GlusterFS module has a symlink, 'doc', to its corresponding
> directory in the doc/code tree.
>
> Taking glusterd for example. With this scheme, there will be
> doc/code/xlators/mgmg/glusterd directory which will contain the relevant
> documentation to glusterd. This directory will be symlinked to
> xlators/mgmt/glusterd/src/doc .
>
> This organization should allow for easy reference by developers when
> developing on GlusterFS and also allow for easy hosting of the documents
> when we set it up.
> ```
>


I haven't read the previous thread, but having doc dir co-exist with src in
each module would encourage (or at least remind) keeping doc updated along
with src changes.  Generally recommended not to store symlinks in the
source repo (though git supports it I think). You could create symlinks
from top level doc/code to per module (or vice versa) in autogen.sh.

Thanks
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://supercolony.gluster.org/pipermail/gluster-devel/attachments/20140722/c3b860c2/attachment.html>