प्रोटोबफ दस्तावेज जेनरेट करें?

Question

क्या किसी को .proto स्रोत फ़ाइलों का उपयोग करके Google Protobuf दस्तावेज़ उत्पन्न करने के लिए एक अच्छा टूल पता है?

Answer 1

डॉक्सीजन तथाकथित इनपुट फ़िल्टर का समर्थन करता है, जो आपको कोड को कुछ डॉक्सिजन समझ में बदलने की अनुमति देता है। प्रोटोबफ आईडीएल को सी ++ कोड में बदलने के लिए इस तरह के एक फ़िल्टर को लिखना (उदाहरण के लिए) आपको .proto फ़ाइलों में डॉक्सीजन की पूरी शक्ति का उपयोग करने की अनुमति देगा। Doxygen FAQ के आइटम 12 देखें।

मैंने सीएमके के लिए कुछ ऐसा किया, इनपुट फ़िल्टर सिर्फ सीएमके मैक्रोज़ को बदलता है और सी फंक्शन घोषणाओं में कार्य करता है। आप इसे here पा सकते हैं।

Answer 2

https://code.google.com/apis/protocolbuffers/docs/techniques.html

स्व का वर्णन संदेश

प्रोटोकॉल बफ़र अपने स्वयं के प्रकार के विवरण शामिल नहीं है। इस प्रकार, संबंधित .proto फ़ाइल के बिना केवल एक कच्चा संदेश दिया गया है, इसके प्रकार को परिभाषित करना, किसी भी उपयोगी डेटा को निकालना मुश्किल है।

हालांकि, ध्यान दें कि .proto फ़ाइल की सामग्री स्वयं प्रोटोकॉल बफर का उपयोग करके प्रतिनिधित्व कर सकती है। स्रोत कोड पैकेज में फ़ाइल src/google/protobuf/descriptor.proto फ़ाइल संदेश प्रकार को परिभाषित करता है। प्रोटोक फ़ाइलडिस्क्रिप्टरसेट आउटपुट कर सकता है - जो --descriptor_set_out विकल्प का उपयोग कर .proto फ़ाइलों के एक सेट का प्रतिनिधित्व करता है। इसके साथ, आप स्वयं-वर्णन प्रोटोकॉल संदेश को परिभाषित कर सकते हैं जैसे:

संदेश SelfDescribingMessage {// .proto फ़ाइलों का सेट जो प्रकार को परिभाषित करता है। आवश्यक FileDescriptorSet proto_files = 1;

// संदेश प्रकार का नाम। // proto_files में फ़ाइलों में से एक द्वारा परिभाषित किया जाना चाहिए। आवश्यक स्ट्रिंग type_name = 2;

// संदेश डेटा। आवश्यक बाइट्स message_data = 3; }

डायनामिक मैसेज (सी ++ और जावा में उपलब्ध) जैसे वर्गों का उपयोग करके, आप फिर ऐसे टूल लिख सकते हैं जो SelfDescribingMessages में हेरफेर कर सकते हैं।

सभी ने कहा कि यह कार्यक्षमता प्रोटोकॉल बफर लाइब्रेरी में शामिल नहीं है क्योंकि हमने Google के अंदर के लिए कभी इसका उपयोग नहीं किया है।

Answer 3

चूंकि .proto फ़ाइल अधिकतर घोषणा है, इसलिए मुझे आमतौर पर पता चलता है कि इनलाइन टिप्पणियों वाली स्रोत फ़ाइल सरल और प्रभावी दस्तावेज़ीकरण है।

Answer 4

एक ओपन सोर्स प्रोटोबफ प्लगइन जो प्रोटोक फाइलों से डॉकबुक और पीडीएफ उत्पन्न करता है।

http://code.google.com/p/protoc-gen-docbook/

अस्वीकरण: मैं प्लगइन के लेखक हूँ।

Answer 5

प्रोटोबफ 2.5 में आपके //proto फ़ाइलों में डाली गई "//" टिप्पणियां वास्तव में इसे जेवाडोक टिप्पणियों के रूप में जेनरेट किए गए जावा स्रोत कोड में बनाती हैं।अधिक विशेष रूप से प्रोटोक कंपाइलर आपकी "//" टिप्पणियां इस तरह ले जाएगा:

// 
// Message level comments 
message myMsg { 

    // Field level comments 
    required string name=1; 
} 

आपकी जेनरेट की गई जावा स्रोत फ़ाइलों में जाएगा। कुछ कारणों से प्रोटोक ने <pre> टैग में जावाडोक टिप्पणियां संलग्न की हैं। लेकिन यह सब v2.5 में एक अच्छी नई सुविधा है।

Answer 6

धागा पुराना है, लेकिन सवाल अभी भी प्रासंगिक लगता है। मेरे पास Doxygen + proto2cpp के साथ बहुत अच्छे परिणाम हुए हैं। proto2cpp Doxygen के लिए एक इनपुट फ़िल्टर के रूप में काम करता है।

Answer 7

askldjd के उत्तर के अतिरिक्त, मैं https://github.com/estan/protoc-gen-doc पर अपना स्वयं का टूल इंगित करना चाहता हूं। यह एक प्रोटोकॉल बफर कंपाइलर प्लगइन भी है, लेकिन बॉक्स के बाहर एचटीएमएल, मार्कडाउन या डॉकबुक उत्पन्न कर सकता है। इसे किसी भी टेक्स्ट आधारित प्रारूप को उत्पन्न करने के लिए मूंछ टेम्पलेट्स का उपयोग करके भी अनुकूलित किया जा सकता है।

प्रलेखन टिप्पणियां /** ... */ या /// ... का उपयोग करके लिखी गई हैं।

Answer 8

[अद्यतन: अगस्त 2017 protoc पीढ़ी-बग से भरा जाओ फिर से लिखने के लिए अनुकूलित है, वर्तमान में 1.0.0-rc]

protoc-doc-gen, @estan द्वारा बनाई गई (यह भी देखें his earlier answer) एक अच्छा और आसान तरीका प्रदान एचटीएमएल, जेसन, मार्कडाउन, पीडीएफ और अन्य प्रारूपों में अपना दस्तावेज उत्पन्न करने के लिए।

1. estan नहीं रह गया है protoc-doc-gen की देखभाल करने वाले है, लेकिन pseudomuto
2. इसके विपरीत क्या मैं विभिन्न पृष्ठों पर पढ़ा है यह है के लिए है:

   वहाँ है कि मैं उल्लेख करना चाहिए अतिरिक्त चीजों की संख्या में हैं टिप्पणियों के भीतर समृद्ध इनलाइन स्वरूपण (बोल्ड/इटैलिक, लिंक, कोड स्निपेट इत्यादि) का उपयोग करने के लिए संभव है

3. protoc-gen-doc गो में पूरी तरह से लिखा गया है और अब पीढ़ी के लिए डॉकर का उपयोग करता है (के बजाय)

भंडार अब यहाँ है: https://github.com/pseudomuto/protoc-gen-doc

मैं के लिए एक उदाहरण भंडार बनाया है दूसरी बात को प्रदर्शित करने के लिए एक अच्छा प्रारूप में Dat Project Hypercore प्रोटोकॉल प्रलेखन ऑटो उत्पन्न करते हैं।

आपको कम से विभिन्न html और markdown उत्पादन पीढ़ी विकल्प देख सकते हैं (या इतने पर एक markdown उदाहरण के लिए here नज़र डालें):

• https://github.com/aschrijver/protoc-gen-doc-example

TravisCI स्क्रिप्ट है कि सभी स्वचालन करता है सरल .travis.yml फ़ाइल:

sudo: required 

services: 
    - docker 

language: bash 

before_script: 
    # Create directory structure, copy files 
    - mkdir build && mkdir build/html 
    - cp docgen/stylesheet.css build/html 

script: 
    # Create all flavours of output formats to test (see README) 
    - docker run --rm -v $(pwd)/build:/out -v $(pwd)/schemas/html:/protos:ro pseudomuto/protoc-gen-doc 
    - docker run --rm -v $(pwd)/build/html:/out -v $(pwd)/schemas/html:/protos:ro -v $(pwd)/docgen:/templates:ro pseudomuto/protoc-gen-doc --doc_opt=/templates/custom-html.tmpl,inline-html-comments.html protos/HypercoreSpecV1_html.proto 
    - docker run --rm -v $(pwd)/build:/out -v $(pwd)/schemas/md:/protos:ro pseudomuto/protoc-gen-doc --doc_opt=markdown,hypercore-protocol.md 
    - docker run --rm -v $(pwd)/build:/out -v $(pwd)/schemas/md:/protos:ro -v $(pwd)/docgen:/templates:ro pseudomuto/protoc-gen-doc --doc_opt=/templates/custom-markdown.tmpl,hypercore-protocol_custom-template.md protos/HypercoreSpecV1_md.proto 

deploy: 
    provider: pages 
    skip_cleanup: true   # Do not forget, or the whole gh-pages branch is cleaned 
    name: datproject   # Name of the committer in gh-pages branch 
    local_dir: build   # Take files from the 'build' output directory 
    github_token: $GITHUB_TOKEN # Set in travis-ci.org dashboard (see README) 
    on: 
    all_branches: true  # Could be set to 'branch: master' in production 

(पीएस: hypercore प्रोटोकॉल Dat Project विकेंद्रीकृत पीयर-टू-पीयर अनुप्रयोगों के निर्माण के लिए मॉड्यूल के पारिस्थितिक तंत्र के मुख्य विनिर्देशों में से एक है।मैंने अवधारणाओं को प्रदर्शित करने के लिए .proto फ़ाइल का उपयोग किया)