[Commit-gnuradio] [gnuradio] 02/03: grc: add more documentation for embedded python blocks

[git]

This is an automated email from the git hooks/post-receive script.

jcorgan pushed a commit to branch maint
in repository gnuradio.

commit 240fd75770bc71435630768ea4767d55ce24bf2b
Author: Sebastian Koslowski <address@hidden>
Date:   Tue Apr 19 17:16:48 2016 +0200

    grc: add more documentation for embedded python blocks
---
 grc/blocks/epy_block.xml | 25 ++++++++++++++++++-------
 grc/python/Block.py      |  3 ++-
 2 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/grc/blocks/epy_block.xml b/grc/blocks/epy_block.xml
index e56186e..d443d29 100644
--- a/grc/blocks/epy_block.xml
+++ b/grc/blocks/epy_block.xml
@@ -17,29 +17,40 @@
     <value>"""
 Embedded Python Blocks:
 
-Each this file is saved, GRC will instantiate the first class it finds to get
-ports and parameters of your block. The arguments to __init__  will be the
-parameters. All of them are required to have default values!
+Each time this file is saved, GRC will instantiate the first class it finds
+to get ports and parameters of your block. The arguments to __init__  will
+be the parameters. All of them are required to have default values!
 """
+
 import numpy as np
 from gnuradio import gr
 
 class blk(gr.sync_block):
-    def __init__(self, factor=1.0):  # only default arguments here
+    """Embedded Python Block example - a simple multiply const"""
+
+    def __init__(self, example_param=1.0):  # only default arguments here
+        """arguments to this function show up as parameters in GRC"""
         gr.sync_block.__init__(
             self,
-            name='Embedded Python Block',
+            name='Embedded Python Block',   # will show up in GRC
             in_sig=[np.complex64],
             out_sig=[np.complex64]
         )
-        self.factor = factor
+        self.factor = example_param
 
     def work(self, input_items, output_items):
+        """example: multiply with constant"""
         output_items[0][:] = input_items[0] * self.factor
         return len(output_items[0])
 </value>
     <type>_multiline_python_external</type>
     <hide>part</hide>
     </param>
-    <doc>Doc me, baby!</doc>
+    <doc>This block represents an arbitrary GNU Radio Python Block.
+
+Its source code can be accessed through the parameter 'Code' which opens your 
editor. Each time you save changes in the editor, GRC will update the block. 
This includes the number, names and defaults of the parameters, the ports 
(stream and message) and the block name and documentation.
+
+Block Documentation:
+(will be replaced the docstring of your block class)
+</doc>
 </block>
diff --git a/grc/python/Block.py b/grc/python/Block.py
index 4118fda..8509aa3 100644
--- a/grc/python/Block.py
+++ b/grc/python/Block.py
@@ -244,6 +244,7 @@ class Block(_Block, _GUIBlock):
         platform = flowgraph.get_parent()
         param_blk = self.get_param('_io_cache')
         param_src = self.get_param('_source_code')
+        doc_end_tag = 'Block Documentation:'
 
         src = param_src.get_value()
         src_hash = hash(src)
@@ -267,7 +268,7 @@ class Block(_Block, _GUIBlock):
 
         self._epy_source_hash = src_hash
         self._name = blk_io.name or blk_io.cls
-        self._doc = blk_io.doc
+        self._doc = self._doc.split(doc_end_tag)[0] + doc_end_tag + '\n' + 
blk_io.doc
         self._imports[0] = 'from {} import {}'.format(self.get_id(), 
blk_io.cls)
         self._make = '{}({})'.format(blk_io.cls, ', '.join(
             '{0}=${0}'.format(key) for key, _ in blk_io.params))