关闭

技术文档的作用

标签: 技术团队文档
97人阅读 评论(0) 收藏 举报
分类:

1. 概述

  • 在做项目的过程中,发现居然有人不知道技术文档的作用,以及如何写技术文档,可能因为所处环境的特殊,大家对基本的计算机知识都不是很懂吧!我查了一些资料,根据自己的理解,谈一谈技术文档吧!

2. 概念

  • 技术文档:使用技术文档,主要也是为了加快团队之间的沟通,别人可以很好的理解你做的这些模块的功能。帮助别人在不需要理解你的代码的前提下,很方便的调用你的模块功能。

3. 示例

3.1 API接口文档

3.1.1 接口示例

资源信息接口

简要描述:

  • 用户获取资源(游戏、视频)基本信息,利用基本信息可获得资源数据

请求URL:
- http://xx.com/search

请求方式:
- GET

参数:

参数名 必选 类型 说明
type string 资源类型(game/video)
limit int 搜索结果数量
item string 资源标题关键字

返回示例

  {
    "resultCount": 2,
    "results": 
    [{
      "id": "db8b9f7f0ca4d269927dc0e9b78fd0f8",
      "kind": "video",
      "title": "apple",
      "info": "视频介绍" ,
      "previewTitle":"预览图名",
      "releaseDate":"2000-09-26 07:00:00",
      "trackTimeMillis":211600,
      "sourceUrl":"192.168.3.100\/videoSource\/"
     }
  }

返回参数说明

参数名 类型 说明
id int 资源ID
kind string 资源种类(game/video)
title string 资源名称
info string 资源基本介绍
previewTitle string 资源图标名称
releaseDate string 资源发布时间
trackTimeMillis bigint 视频长度(单位:s)
sourceUrl string 文件资源(图标、截图等)的路径

3.1.2 说明

  • 通过该接口,前端人员边可以很方便的了解了后台接口需要提交什么请求,能够获得什么数据,才可以根据后台提供的数据进行整合,把后台提供的原材料煮成一道道菜出来。

3.2 Android平台SDK文档

3.2.1 文档示例

这是微博的SDK文档中分享微博功能实现的说明文档。
1) 分享前准备工作
在进行微博分享前,需要在AndroidManifest.xml中,在需要接收消息的Activity(唤起微博主程序的类)里声明对应的Action:ACTION_SDK_REQ_ACTIVITY,如下所示:

<activity
    android:name="com.sina.weibo.sdk.demo.WBShareActivity"
    android:configChanges="keyboardHidden|orientation"
    android:screenOrientation="portrait" >
    <intent-filter>
            <action android:name="com.sina.weibo.sdk.action.ACTION_SDK_REQ_ACTIVITY" />
            <category android:name="android.intent.category.DEFAULT" />
</intent-filter>
</activity>
<activity 
     android:name="com.sina.weibo.sdk.component.WeiboSdkBrowser" 
     android:configChanges="keyboardHidden|orientation"
     android:windowSoftInputMode="adjustResize"
     android:exported="false" >
</activity>

2) 分享实现
① 在onCreate函数创建微博分享接口实例,并进行注册,请确保先注册,后分享

mWeiboShareAPI = WeiboShareSDK.createWeiboAPI(this, Constants.APP_KEY);
mWeiboShareAPI.registerApp();   // 将应用注册到微博客户端

② 创建要分享的内容

private TextObject getTextObj() {
    TextObject textObject = new TextObject();
    textObject.text = getSharedText();
    return textObject;
}

③ 通过IWeiboShareAPI#sendRequest唤起微博客户端发博器进行分享

private void sendMultiMessage(boolean hasText, boolean hasImage, boolean hasWebpage,
        boolean hasMusic, boolean hasVideo, boolean hasVoice) {
    WeiboMultiMessage weiboMessage = new WeiboMultiMessage();//初始化微博的分享消息
    if (hasText) {
        weiboMessage. textObject = getTextObj();
    }
    SendMultiMessageToWeiboRequest request = new SendMultiMessageToWeiboRequest();
    request.transaction = String.valueOf(System.currentTimeMillis());
    request.multiMessage = weiboMessage;
    mWeiboShareAPI.sendRequest(request); //发送请求消息到微博,唤起微博分享界面
}

④ 实现IWeiboHandler#Response接口,接收分享后微博返回的数据

protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    mWeiboShareAPI.handleWeiboResponse(intent, this); //当前应用唤起微博分享后,返回当前应用
}
@Override
public void onResponse(BaseResponse baseResp) {//接收微客户端博请求的数据。
    switch (baseResp.errCode) {
    case WBConstants.ErrorCode.ERR_OK:      .........
        break;
    case WBConstants.ErrorCode.ERR_CANCEL: .........
        break;
    case WBConstants.ErrorCode.ERR_FAIL:    .........
        break;
    }
}

3.2.2 说明

  • 微博的SDK文档中通过实例详细的介绍了每个接口如何实现,用户仅需将SDK导入到项目中,通过这些说明步骤,便可以很方便的使用SDK提供的功能,而不需要了解其内部具体是怎么实现的,即封装性。

参考资料

  • 微博Android平台SDK文档
0
0

查看评论
* 以上用户言论只代表其个人观点,不代表CSDN网站的观点或立场
    个人资料
    • 访问:3725次
    • 积分:117
    • 等级:
    • 排名:千里之外
    • 原创:8篇
    • 转载:2篇
    • 译文:0篇
    • 评论:0条
    文章存档