sqoop-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Gwen Shapira (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (SQOOP-1680) DOC: Create an API doc for the Sqoop repository.
Date Wed, 05 Nov 2014 18:26:33 GMT

    [ https://issues.apache.org/jira/browse/SQOOP-1680?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14198783#comment-14198783

Gwen Shapira commented on SQOOP-1680:

I'd rather not duplicate docs, and the repository also have JavaDocs.
I thought JavaDocs are the standard method for documenting internal APIs. 

Using my usual example:
Kafka has an excellent ConfigDef library used internally. The JavaDocs are great and ensured
new devs use this correctly, but there's no other documentation, since this is internal. Producer
and Consumer are external and have real documentation which we maintain, with specific examples
on how to use them, best practices, etc.

>  DOC: Create an API doc for the Sqoop repository.
> -------------------------------------------------
>                 Key: SQOOP-1680
>                 URL: https://issues.apache.org/jira/browse/SQOOP-1680
>             Project: Sqoop
>          Issue Type: Bug
>            Reporter: Veena Basavaraj
>            Assignee: Veena Basavaraj
>             Fix For: 1.99.5
> Having a good doc for repository will encourage us to create better code going forward
to support other types of repository.
> Even the repo upgrade can be its own clean api
> Well we have connector developer guide that details the responsibilities. 
> I have similar thoughts for the exec engine and repository.
> You many ask why? If we think ourselves as external developers we will take less shortcuts
and make our code mode extensible and clean is my thought.
> for instance
> Should the create link api enforce the unique constraint on name or the database table
should. these are not documented anywhere clearly for someone trying to add a new repo and
the recommended practices are nice to have

This message was sent by Atlassian JIRA

View raw message